The JIRA Portlet macro, for JIRA 3.x and earlier, allows you to display a JIRA dashboard portlet on a Confluence page. JIRA is the issue tracking and project management system supplied by Atlassian. Using JIRA 4.0 and LaterSetting up new JIRA portlets will not work when using JIRA 4.0 and later. Please consider using a JIRA gadget instead of a JIRA Portlet macro.
| On this page:
|
Using JIRA 3.x
The JIRA portlet macro appears as shown in the screenshot below.
Screenshot above: The JIRA Portlet Macro in Confluence
Obtaining the JIRA Portlet URL
The JIRA Portlet macro requires the URL of the JIRA portlet 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 add the JIRA Portlet macro to a page:
- In the Confluence editor, choose Insert > Other Macros.
- Find and select the required macro.
Parameters
When editing, you can click on the macro placeholder and choose Edit to display the parameters for this macro in the Macro Browser.
Parameters are options that you can set for Confluence macros to control the content or format of the macro output. The table below lists parameters for this macro that can be set in the Macro Browser.
Parameter | Required | Default | Description |
---|---|---|---|
JIRA Portlet URL | yes | none | URL of the JIRA portlet, as described above. |
Anonymous Retrieval | no | false | For Confluence 2.7.0 and later. If this parameter is selected, 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 not set, 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 | 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. |
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. |
|
| 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. |
|
| 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 Atlassian Answers. 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's Guide.