JIRA is Atlassian's issue tracking and project management system. By adding the JIRA Issues macro to a Confluence page, you can display one or more issues from a JIRA site. You can also choose to create an issue in JIRA, at the time of adding the macro to the Confluence page.
Before you can use this macro, your Confluence and JIRA sites must be connected via Application Links. People viewing the page will see the publicly accessible issues from the JIRA site. If your JIRA site has restricted viewing (that is, people need permission to view issues) then they will need to authenticate before seeing the restricted issues. See more about restricted JIRA issues below. Note: Your Application Links are automatically configured in Confluence OnDemand.
What you can do with the JIRA Issues macro
Using the JIRA Issues macro, you can:
- Display a table of JIRA issues on your page, based on the results of a search using JIRA Query Language (JQL).
- Display a table of JIRA issues onto your page, using a JIRA URL.
- Display a single issue from the JIRA site, or a subset of selected issues from your JIRA search results.
- Display a count of issues from the JIRA site.
- Create a new issue on the JIRA site and display that issue on your page.
Adding and updating the JIRA Issues macro – an overview
Quick guide to using the macro on a Confluence page:
Speeding up macro entry with autocomplete: Type { and the beginning of the macro name, to see a list of suggested macros. Details are in Using Autocomplete. To edit an existing macro: Click the macro placeholder and choose Edit. A macro dialog window will open, where you can edit the parameters of the macro.
On this page:
- What you can do with the JIRA Issues macro
- Adding and updating the JIRA Issues macro – an overview
- Displaying issues via a JIRA Query Language (JQL) search
- Displaying issues via a JIRA URL
- Displaying a single JIRA issue, or selected JIRA issues
- Displaying a count of issues
- Creating a new issue in JIRA
- Configuring Application Links to display restricted JIRA issues (Not applicable to Confluence OnDemand.)
- Rendering HTML from JIRA
- Disabling the JIRA Issues macro
- Notes
- Code examples for this macro
Related pages:
Screenshot: Example of JIRA issues macro on a Confluence page
Displaying issues via a JIRA Query Language (JQL) search
You can use the macro to display a table of JIRA issues on your page, based on the results of a search using JIRA Query Language (JQL).
JQL is a simple query language, similar to SQL, which works in JIRA. A basic JQL query consists of a field, followed by an operator (such as = or >), followed by one or more values or functions.
Examples:
The following query will find all issues in the 'TEST' project:
project = "TEST"
The following query will find all issues in the 'documentation' component of the 'CONF' project:
project = CONF and component = documentation
For more information about JQL syntax, see the JIRA documentation: Advanced Searching.
To display a table of issues based on a JQL search:
- Insert the JIRA Issues macro onto your Confluence page, as described above.
- Choose a JIRA server next to the Search button.
- If prompted, log in to the JIRA server.
- Enter the JQL query into the Search box.
- Choose Search.
- If you want to customise the display, choose Display options and adjust the columns that will appear in your table of issues.
- Choose Insert.
Screenshot: The JIRA Issues macro browser with a JQL search, and display options
Displaying issues via a JIRA URL
You can paste any of the following JIRA URLs into the JIRA Issues macro. Confluence will immediately convert the URL to a JQL search.
- Any URL for a JIRA issue search or filter.
- A URL for a single issue.
- The URL of the XML view of a JIRA search.
Auto-convert: You can paste a JIRA URL directly into the Confluence editor (without calling up the macro browser). Confluence will automatically convert the URL into a JIRA Issues macro.
Displaying a single JIRA issue, or selected JIRA issues
To display a single JIRA issue, choose one of the following methods:
- Paste the URL of the issue directly onto the Confluence page. (There is no need to use the macro browser.) Confluence will auto-convert the link to a JIRA Issues macro.
- Or: Add the JIRA issues macro to the page as described above, and choose Recently Viewed to see the JIRA issues you have visited recently. Select an issue and choose Insert.
- Or: Add the JIRA issues macro to the page as described above, and past the issue URL into the search box in the macro browser.
- Or: Add the JIRA issues macro to the page, define your search criteria in the macro browser via JQL as described above, then select the check box next to the issue in the search results, within the macro browser.
To display a subset of JIRA issues from your search results:
- Add the JIRA issues macro to the page.
- Define your search criteria in the macro browser via JQL, as described above.
- Select the check boxes next to the required issues in the search results, within the macro browser.
Screenshot: Selecting a subset of issues to display
Displaying a count of issues
You can choose to display the number of issues returned by your search, rather than a table of issues. The JIRA Issues macro will display a count of issues, linked to the search in JIRA.
Screenshot: The JIRA Issues macro displaying an issue count on a Confluence page
To display an issue count:
- Add the JIRA issues macro to the page.
- Define your search criteria in the macro browser via JQL, as described above.
- Choose Display options, then choose Total issue count next to 'Display options' in the macro browser.
- Choose Insert.
Creating a new issue in JIRA
While editing a Confluence page, you can create an issue in JIRA and display it on your Confluence page, without leaving the Confluence editor.
To insert an issue into JIRA:
- Add the JIRA Issues macro to the page, as described above.
- Choose Create New Issue.
- Supply the information about your JIRA server, project, and issue, as prompted.
- Choose Insert.
Confluence will send a request to JIRA, to add the issue to the JIRA site. Confluence will also display the resulting JIRA issue on the Confluence page.
Notes:
- This feature works best with JIRA issue types whose mandatory field requirements have not been altered. With the exception of a JIRA issue's 'Component/s' or 'Fix Version/s' fields, You cannot use the JIRA Issies macro to add an issue whose issue type has customised mandatory field requirements. (Exception: customisations of the 'Component/s' and 'Fix Version/s' fields are accepted.)
- If your JIRA project has customised fields, the JIRA Issues macro will not prompt you for information for those fields. In other words, those fields will not appear in the 'Create New Issue' dialog in the JIRA Issues macro browser.
Configuring Application Links to display restricted JIRA issues (Not applicable to Confluence OnDemand.)
Before you can use this macro, your Confluence and JIRA sites must be connected via Application Links.
If the JIRA site allows anonymous viewing of issues, you must configure an application link, but there is no need to configure any incoming or outgoing authentication between JIRA and Confluence. People viewing the Confluence page will see the publicly accessible issues from the JIRA site.
If your JIRA site has restricted viewing, or if some JIRA projects or issues are restricted to viewing by certain people, then people will need to log in before seeing the restricted issues.
In such a case, the outgoing authentication in the Confluence Application Links determines how the JIRA Issues macro handles restricted issues:
- If the outgoing authentication is set to Trusted Applications, people can see restricted issues in JIRA if their username is the same in JIRA and Confluence, and if they have permission in JIRA to see the issue.
- If the outgoing authentication is set to OAuth, people may need to choose Login & Approve, to gain access to the JIRA server and restricted issues.
- If the outgoing authentication is set to Basic Access, people can see the JIRA issues that are visible to the user account configured in JIRA's outgoing authentication setting.
Rendering HTML from JIRA
Formatted fields from JIRA can be displayed in Confluence if you set up a Confluence-to-JIRA application link. Otherwise, such formatted fields will be escaped within the output of the JIRA issues macro. This is to prevent the possibility of malicious HTML being served by an untrusted JIRA server. The most likely field where you will notice this is in the description field.
This example shows how a description column may be displayed in JIRA:
This is
- the description
- of my issue
If there is no application link between JIRA and Confluence, the description will appear in the JIRA issues macro like this:
<p>This is<ul><li>the description</li><li>of my issue</li></ul></p>
Disabling the JIRA Issues macro
The functionality is provided by an add-on (plugin) called 'JIRA Macros'. To make the macro unavailable on your site, you can disable the add-on. See Disabling and Enabling Add-ons.
Notes
Not applicable to Confluence OnDemand. HTTPS: The JIRA Issues macro can access a JIRA site running under SSL provided the Confluence server is configured to accept the JIRA SSL certificate. See Connecting to LDAP or JIRA or Other Services via SSL.
Custom fields can be added as columns to the table simply by using the name of the field with no quotes. Earlier versions of the macro required you to use the custom field id, e.g. customfield_10100.
Code examples for this macro
Note: Wiki markup offers a few additional parameters that are not available via the macro browser.
See:
Attachments:
































