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 and Later

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.

Despite the above, gadgets replaced portlets in JIRA 4.0. Hence, consider using a JIRA gadget instead.

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,

Log in to your JIRA system.
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.)
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.)
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,

Open the Confluence page or blog post that you want to edit, then click the 'Edit' button.
Click the Macro Browser icon on the toolbar. The macro browser window will open.
Scroll through the list of macros to find the one you want. Alternatively, start typing the macro name into the search box at the top right of the macro browser. Macros with a matching name will appear in the main pane.
Click the desired macro.
Set the macro parameters to your requirements. If desired, you can preview these changes by clicking 'Refresh'.
Click 'Insert' to add the macro onto the page.

You can also insert macros via autocomplete. For more information, see Using Autocomplete in the Rich Text Editor.

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,

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

Parameters

Parameters are options that you can include in Confluence macros to control the content or format of the macro output. The table below lists relevant parameters for this macro.

Parameter names are different in the macro browser and in wiki markup. Below we show the macro browser parameter names in bold text, and the equivalent wiki markup parameters in (bracketed) text. If we do not show any parameter name for the wiki markup, then you should leave out the parameter name and simply include the parameter value as the first parameter, immediately after the colon (:).

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:

Error rendering macro 'excerpt-include'

User 'null' does not have permission to view the page.

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.

Child pages