Confluence Docs 3.0 : JIRA Issues Macro This page last changed on Oct 27, 2009 by ggaskell. JIRA is the issue tracking and project management system supplied by Atlassian. The Jira Issues macro allows you to display a list of issues from a JIRA site within a page in Confluence. In other words, if you have your own JIRA site, your Confluence page can show a list of issues from your JIRA project. You can also show a list of issues from any JIRA site to which you and your readers have access. Screenshot: Example of JIRA Issues shown on a Confluence page On this page: Usage with the Macro Browser Usage with the Wiki Markup Editor Displaying a List of JIRA Issues on a Confluence Page Parameters Issues Displayed a Page at a Time Example Displaying Issues which have Restricted Viewing Troubleshooting ## Usage with the Macro Browser To insert the JIRA issues macro into a page using the Macro Browser, Open your desired Confluence page, then click the 'Edit' button. The 'Edit Page' mode opens. Next, click the Macro Browser icon on the editor toolbar. The Macro Browser will open in the middle of the screen. 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've found the JIRA issues macro, click 'insert' to add it to your page. ## Usage with the Wiki Markup Editor The basic syntax is:
    {jiraissues:url=<URL of your JIRA XML view>}
5. - - ## Displaying a List of JIRA Issues on a Confluence Page Step 1 — Obtain the URL of the Issue Filter Log in to your JIRA system. Go to the 'Issues' screen and create a new filter. Do not modify an existing filter. This is the 'Find Issues' screen in JIRA 3.13.x and earlier. Set up your search parameters and use 'View' to check the issues returned. Once the filter is finished, go to the Filter's 'View' tab/section in the top-left area of the JIRA interface. Copy the XML link. To do this, follow the appropriate steps below: If you are using JIRA 4.0.x or later: Click the 'Views' menu, right-click the 'XML' item and copy the XML link.
   - 1. If you are using JIRA 3.13.x or earlier: Locate the 'Current View' links section (see example below) and find the 'XML' link.
     2. Copy the 'XML' link to your clipboard.
3. Step 2 — Embed the 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:
       {jiraissues:url=CONTENT}
Replace 'CONTENT' with the JIRA filter URL from your clipboard. Customise the macro output by adding optional parameters. See below. Save the 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 (`:`). The JIRA Issues macro allows the following parameters:
Parameter | Required | Default | Description
--- | --- | --- | ---
Anonymous Retrieval (`anonymous`) | no | false | 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 | The value of the 'url' parameter | If you specify a 'baseurl', then the link in the header, pointing to your JIRA site, will use this base URL instead of the value of the 'url' parameter. This is useful when Confluence connects to JIRA with a different URL from the one used by other users.
JIRA Field Columns to Display (`columns`) | no | By default, the following columns are shown: type key summary assignee reporter priority status resolution created updated due | A list of JIRA column names, separated by semi-colons (;). Example columns are: key, summary, type, created, fixversion, updated, due, assignee, reporter, priority, status and resolution. You can include any columns recognised by your JIRA site, including custom columns.
Display Total Numbers Only (`count`) | no | false | If this parameter is set to 'true', the issue list will show the number of issues in JIRA. The count will be linked to your JIRA site.
Cache (`cache`) | no | on | The macro maintains a cache of the issues which result from the JIRA query. If the 'cache' parameter is set to 'off', the relevant part of the cache is cleared each time the macro is reloaded. (The value 'false' also works and has the same effect as 'off'.)
Height (Pixel Value Only) (`height`) | no | 480 | The height in pixels of the table displaying the JIRA issues. Note that this height specification is ignored in the following situations: If you set the 'renderMode' parameter (see below) to 'static'. When the JIRA issues are displayed in a PDF or Word document, in an email message or in an RSS feed.
(`renderMode`) | no | In formats not mentioned below, the default is 'dynamic'. The default is 'static' when the JIRA issues are displayed in a PDF or Word document, in an email message or in an RSS feed. | By default, the JIRA Issues macro offers a dynamic display with the following features: Click the column headers to sort the output. Drag and drop the columns into a different order. Temporarily remove a column from the display. View a page of issues at a time, for faster response times. Set the 'renderMode' parameter to 'static' if you want to disable the dynamic display features.
Title (`title`) | no | JIRA Issues | You can customise the title text at the top of the JIRA issues table with this parameter. For instance, setting the title to 'Bugs-to-fix' will replace the default 'JIRA Issues' text. This can help provide more context to the list of issues displayed.
URL (`url`) | yes | none | The URL of the XML view of your selected issues in JIRA Issue Navigator. Note: If the URL in the 'url' parameter does not contain a `tempMax` argument, then the value of `tempMax` will default to 500. If your JIRA server is version 3.12 or earlier, this means that the JIRA Issues macro will return a maximum of 500 issues. If your JIRA server is version 3.13 or later, a value of 500 means that the JIRA Issues macro will return a maximum of 500 issues per page.
Width (`width`) | no | 100% | The width of the table displaying the JIRA issues. Can be indicated either as a percentage (%) or in pixels (px).
## Issues Displayed a Page at a Time If you are using JIRA 3.13 or later, the JIRA Issues macro will retrieve and show a 'page' of issues at a time. The buttons underneath the table allow you to move to the next or previous page, or to the start or end of the list. The number of issues retrieved per page is determined by the `url` parameter — see the description of the macro parameters above. If your version of JIRA is 3.12 or earlier, the JIRA Issues macro will retrieve all the issues at once and display them as a single 'page'. ## 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://jira.atlassian.com/sr/jira.issueviews:searchrequest-xml/temp/SearchRequest.xml?&query=jiraissues&summary=true&description=true&body=true&pid=10470&tempMax=10|columns=type;key;summary`} The example code contains three parameters (see above parameter table for their meanings): `anonymous=true` `url=`<a long URL derived from the XML view of a JIRA filter> `columns=type;key;summary` Below are the results of the above macro markup, displayed on this Confluence page:
JIRA Issues (10 issues)
Type | Key | Summary
--- | --- | ---
| CONF-1181 | Parse exception in jiraissues
| CONF-4472 | jiraissues macro is broken in Preview mode
| CONF-3729 | robust (and safer) {jiraissues} macro authentication
| CONF-6878 | jiraissue macro not including desired columns
| CONF-2711 | Better authentication method for jiraissues and jiraportlet macros
| CONF-1595 | Better authentication method for jiraissues and jiraportlet macros
| CONF-4897 | Using JIRA base-URL for JIRAPORTLET and JIRAISSUES links
| CONF-854 | ParseException when trying to use rss / jiraissues macro
| CONF-5303 | Using JIRA base-URL for JIRAISSUES links
| CONF-11829 | jiraissues macro issues when multiple on page
## Displaying Issues which 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. This section explains how to handle JIRA issues that have restricted viewing. ##### Using Confluence-to-JIRA Trusted Communication (Recommended) For Confluence 2.7.0 and later and JIRA 3.12 and later, your administrator can set up trusted communication between Confluence and JIRA. The entire process is described in the Confluence Administrator's Guide. Provided that your administrator has set up trusted communication, 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 the section below if you want more detail.
| 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.
##### Specifying Username and Password in the JIRA URL (Not Recommended) If you have not set up trusted communication between JIRA and Confluence and 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 ampersand (&) symbol. ## 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. Refer to the Confluence Knowledge Base article for more information about problems connecting to SSL services. And see also: JIRA Issues Macro FAQ Troubleshooting Trusted Communication between JIRA and Confluence ##### RELATED TOPICS JIRA Portlet Macro Working with Macros In the Administrator's Guide: Configuring JIRA with Confluence Setting Up Trusted Communication between JIRA and Confluence Take me back to the Confluence User Guide. Attachments: copy-to-clipboard.PNG (image/png) navigator-header.PNG (image/png) navigator-header.PNG (image/png) copy-to-clipboard.PNG (image/png) copy-to-clipboard-jira4plus.png (image/png)

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