This page last changed on Jan 15, 2008 by pkamal.

JIRA is the issue tracking and project management system supplied by Atlassian. The JIRA Portlet macro allows you to display a JIRA dashboard portlet on a Confluence page.

To do this, you will need to include the URL of the portlet in the macro.

JIRA Portlet Macro

{jiraportlet:url=urlOfJIRAPortlet}

On this page:

Error formatting macro: toc: java.lang.NullPointerException

Displaying a JIRA Portlet on your Confluence Page

Here's how you locate the URL of a JIRA portlet and put it into your JIRA Portlet macro:

  1. Log in to your JIRA system.
  2. Add the portlet you wish to include in Confluence to your JIRA dashboard. (Once you have copied the portlet's URL into Confluence, you can remove it from your JIRA dashboard.)
  3. Click 'On' beside 'Configure' on your JIRA dashboard. (If you don't see this link, you need to click the 'Manage Portal' link, click the 'Configure' button and then return to the dashboard.)
  4. Right-click the title located at the top-left corner of the portlet and copy its link location. See Screenshot 1.
  5. Log in to your Confluence system.
  6. Paste the link location into the {jiraportlet} macro on your Confluence page.

Screenshot 1: Copy link location

Parameters

Parameter Required Default Description
url yes none URL of the JIRA portlet, as described above.
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.
baseurl no none If Confluence retrieves the JIRA portlet from some other URL than JIRA's public URL, you should supply JIRA's public URL in the baseurl parameter.

Example

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

{jiraportlet:anonymous=true|url=http://jira.atlassian.com/secure/RunPortlet.jspa?portletKey=com.atlassian.jira.plugin.system.portlets:projectstats&description=Stats:%20Confluence%20(Versions)&projectid=10470&statistictype=fixfor&template=/portlets/dashboard/projectstats.jsp}

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

Released 2.8 1
Unreleased 2.8.3 2
Unreleased 2.9 57
   1%
Unscheduled 3878
   98%

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:

Setting Up Trusted Communication between JIRA and Confluence
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.
RELATED TOPICS

JIRA Issues Macro
Working with Macros

In the Administrator's Guide:

Take me back to Confluence User Guide

Document generated by Confluence on Jun 24, 2008 18:06