This page last changed on Apr 06, 2008 by cbroadfoot.
JIRA is the issue tracking and project management system supplied by Atlassian. The Jira Issues macro allows you to display a list of issues matching any JIRA filter within a page in Confluence.
Usage: |
{jiraissues:url=jira_rss_url} |
Description: |
Display a list of JIRA issues on a Confluence page. |
Input: |
See parameters table below. |
Output: |
Nice looking list of issues on a Confluence page. |
Bundled with Confluence? |
|
On this page:
Error formatting macro: toc: java.lang.NullPointerException
Displaying a List of JIRA Issues on a Confluence Page
Stage 1 - Obtain Issue Filter URL
- Log in to your JIRA system.
- Visit the 'Find Issues' screen and create a new filter. Do not modify an existing filter.
- Set up your search parameters and use 'View' to check the issues returned.
- Once the filter is finished, visit the 'Filter View' tab, located above and to the left of the 'View' button.
- From the 'Filter View' tab, locate the 'Current View' links section (see example below) and find the 'XML' link.
- Copy the 'XML' link to your clipboard.
Stage 2 - Embed Issue Filter URL onto your Confluence page
- Log in to your Confluence system.
- Edit the page where you wish to display the list of JIRA issues.
- Type the following text into a new line at the appropriate location:
- Replace 'CONTENT' with the JIRA search URL from your clipboard.
- Customise the macro output by adding optional parameters (see below) as required.
- Save the Confluence page.
Parameters
The following parameters can be embedded in the macro call:
Parameter |
Required |
Default |
Description |
url |
yes |
none |
The URL of the XML view of your selected issues in Jira Issue Navigator. |
anonymous |
no |
false |
For Confluence 2.7.0 and later. If this parameter is set to 'true', JIRA will return only the issues which allow unrestricted viewing i.e. the issues which are visible to anonymous viewers, as determined by JIRA's viewing restrictions. If this parameter is omitted or set to 'false', then the results depend on how your administrator has configured the communication between JIRA and Confluence. By default, Confluence will show only the JIRA issues which the user is authorised to view. See more details below. |
columns |
no |
none |
a semi-colon delimited list of jira column names. Valid columns are key, summary, type, created, updated, due, assignee, reporter, priority, status and resolution |
count |
no |
false |
true will output the number of issues in JIRA, linking the count to the JIRA instance |
cache |
no |
on |
'off' will refresh the jiraissues cache, forcing a reload on the page before the display |
baseurl |
no |
|
the header link to the issue navigator will use this base url (used when Confluence connects to Jira with a different URL to normal users) |
tempMax |
no |
20 |
limits the number of results you get back. This is the case even when count is set to true. |
Example
Below is an example of some macro markup code, requesting a list of issues from the Atlassian public JIRA site:
{jiraissues:anonymous=true|url=http:
Below are the results of the above macro markup, displayed on this Confluence page:
Displaying Issues which have Restricted Viewing
 | Easy and secure for Confluence 2.7.0 and later
For Confluence 2.7.0 and later, 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 this section if you want more detail. |
This section explains how to handle JIRA issues that 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.
Specifying Username and Password in the JIRA URL (Not Recommended)
For Confluence 2.6.x and earlier, 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 & symbol.
Using Confluence-to-JIRA Trusted Communication (Recommended)
For Confluence 2.7.0 and later, your administrator can set up trusted communication between Confluence and JIRA. The entire process is described in the Confluence Administrator's Guide.
Here is a relevant extract from the above page:
 | Remove the username and password from your macro markup code
Prior to Confluence 2.7, you needed to include a username and password in the macro markup code if you wanted to display JIRA issues which had restricted viewing. Once your administrator has set up trusted communication between Confluence and JIRA, you no longer need to include a username and password in the markup code for your JIRA macros. |
The following options are available for determining the issues which will be retrieved from JIRA and displayed on the Confluence page:
What you want to do |
Macro parameter |
URL parameter |
Comments |
Display the JIRA issues which the logged-in user is authorised to see. And if the user is not logged in, display only issues which allow unrestricted viewing. |
|
|
Do not specify any authentication parameters. In this case, the behaviour depends on the way your administrator has set up trusted communication between JIRA and Confluence. Here is a summary of the behaviour:
- If trusted communication is enabled, the authorisation will work seamlessly. When a logged-in user views your page, they will see only the JIRA issues they are allowed to see. And if they are not logged in, they will see only the issues which allow unrestricted viewing.
- If trusted communication is disabled, the Confluence page will show only the JIRA issues which allow unrestricted viewing.
|
Ensure that Confluence will display only the JIRA issues which allow unrestricted viewing. |
anonymous |
|
Regardless of who the user is (logged in or not), the Confluence page will show only anonymously-visible issues. Confluence will not attempt to set up a trusted communication link with JIRA in this case. |
Use a pre-determined username and password to access the JIRA issues. |
|
&os_username=MYNAME&os_password=MYPASSWORD |
Not recommended. Prior to Confluence 2.7, this was the only way of displaying issues with restricted viewing. For Confluence 2.7 and later, this method will still work. Confluence will not attempt to set up a trusted communication link with JIRA in this case. |
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.
JIRA 3.7 Link Format Change
As a result of RSS feed improvements, the (outdated) JIRA Issues Macro differs between JIRA 3.6 and 3.7.
This is not a concern for users running the latest versions of Confluence and JIRA. However, users using Confluence versions older than 2.2.10 to access JIRA 3.7 must upgrade Confluence or patch the JIRA Issues macro to handle the 3.7 format.
Confluence |
JIRA |
OK |
Action Required |
2.2.10, 2.3 |
Any version |
|
None |
Older than 2.2.10 |
3.7 |
|
Stop Confluence, open your Confluence install directory and remove the file \WEB-INF\lib\jira3.jar. Download the JIRA 3.7 version and rename it to jira3.jar |
Older than 2.2.10 |
Older than 3.7 |
|
None |
And see also:
RELATED TOPICS
JIRA Portlet Macro
Working with Macros
In the Administrator's Guide:
Take me back to Confluence User Guide
|