This page last changed on Oct 26, 2009 by ggaskell.

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

On this page:

Using JIRA 4.0

Please note the following if you intend to upgrade or have already upgraded your JIRA server to JIRA 4.0:

Setting up new JIRA portlets will not work when using Confluence 3.0 or earlier and JIRA 4.0.

Bear in mind that your existing JIRA portlet macros based on earlier versions of JIRA will continue to work in Confluence as they will still be functional in JIRA 4.0. However, due to architectural changes in JIRA 4.0, the ability to create new JIRA 4.0 portlet macros in Confluence 3.0 or earlier is not available. Please refer to JRA-19285 and JRA-18521 for more information.

If you would like the ability to create new JIRA 4.0 portlet macros in Confluence 3.0 or earlier, please vote for JRA-18521. However, we intend to resolve this issue in a future release of Confluence.

Using JIRA 3.x

The JIRA portlet macro appears as shown in the screenshot below.

Screenshot: The JIRA Portlet Macro in Confluence

Obtaining the JIRA Portlet URL

The JIRA portlet macro requires a URL of the JIRA portlet content you wish to show on a Confluence page.

To obtain the JIRA portlet URL,

  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.

Screenshot 1: Copy link location

Usage with the Macro Browser

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

  1. Open your desired Confluence page, then click the 'Edit' button. The 'Edit Page' mode opens.
  2. Next, click the Macro Browser icon on the editor toolbar. The Macro Browser will open in the middle of the screen.
  3. In the Macro Browser, type the name of your desired macro into the search box at the top right of the window. Macros with a matching name will appear in the centre pane. Click on the desired macro to see its options screen. Here, you can set the macro parameters then click 'insert' to put the macro into the page.

Once you have found the JIRA portlet macro, paste your copied JIRA portlet URL into the JIRA Portlet URL field and then click 'insert' to add it to your page.

Usage with the Wiki Markup Editor

To insert the JIRA portlet macro into a page using the Wiki Markup editor,

  1. Log in to your Confluence system.
  2. Paste the copied JIRA portlet URL at the end of the url parameter in a {jiraportlet} macro on your Confluence page.

Parameters

Parameters are settings for Confluence macros that allow the user to control their content or presentation. The table below lists relevant parameters for this macro.

Parameter names are displayed differently in the macro browser interface and in wiki markup. Below, parameter names used in the macro browser are indicated in Bold text, while their equivalents in wiki markup are indicated in (bracketed) text. If the latter is not shown, then in wiki markup, the parameter's name should be omitted and only its value should be added immediately after the colon symbol (:).

Parameter Required Default Description
JIRA Portlet URL
(url)
yes none URL of the JIRA portlet, as described above.
Certain JIRA portlets may require user authentication details in order to display their content. Hence you may need to append: &os_username=yourJiraUsername&os_password=yourJiraPassword to the end of this url.
Anonymous Retrieval
(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.
Base URL
(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 (for JIRA 3.13 or earlier)

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:

Displaying Issues which have Restricted Viewing

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.

Using Confluence-to-JIRA Trusted Communication

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

Ideas for new features or want more tips?

If you have an idea for a new feature, please log it on our JIRA site.

You will also find many hints and tips on our Confluence forum. Try asking a question or sharing your ideas with other Confluence users.

Logging Bugs and Requesting Support

If you have found a bug in this macro, please log it on our JIRA site.

If you encounter a problem using this macro, please raise a ticket on our Support site.

Known Limitations when used with JIRA Calendar

If you are using the JIRA Portlet macro in combination with the JIRA Calendar, paging will work only if your Confluence and JIRA sites are running on the same host. Otherwise, you see error messages like Access to restricted URI.

Reason: the Calendar portlet communicates with JIRA via AJAX requests. Because of security concerns, browsers by default do not allow requests to any host different from the one the page was originally downloaded from.

There is a workaround. If you wish, you can turn off this security check in your browser. The exact way depends on your browser version, so Google for hints.
Please consider all implications of turning off this security check before you perform this action.

There is an existing request to develop support for proxying of the AJAX requests from Confluence to JIRA. If you need this feature, please vote for this issue: JCAL-64.

RELATED TOPICS

JIRA Issues Macro
Working with Macros

In the Administrator's Guide:

Take me back to the Confluence User Guide.

Document generated by Confluence on Nov 05, 2009 23:35