Confluence 5.7 has reached end of life
Check out the [latest version] of the documentation
JIRA is the issue tracking and project management system supplied by Atlassian. 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.
Using the JIRA Issues macro, you can:
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.
Screenshot: Example of JIRA issues macro on a Confluence page
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:
Screenshot: Display options in the JIRA Issues macro browser.
You can paste any of the following JIRA URLs into the JIRA Issues macro. Confluence will immediately convert the URL to a JQL 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.
To display a single JIRA issue, choose one of the following methods:
To display a subset of JIRA issues from your search results:
Screenshot: Selecting a subset of issues to display
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:
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:
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.
Limitations
The JIRA Issues macro will notify you if it is unable to create an issue in the selected project. This may be because the project has a required field, field configuration or other customisation that is not supported by the JIRA Issues macro. In this situation you will need to create the issue directly in JIRA.
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:
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
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>
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 apps.
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.
The following examples are provided for advanced users who want to inspect or edit the underlying markup for a Confluence page.
Macro name: jiraissues
Macro body: None.
Note: A number of additional parameters that are not available via the macro browser are available in storage format and wikimarkup.
Parameter name | Required | Default | Parameter description and accepted values |
---|---|---|---|
| No |
| If this parameter is set to 'true', JIRA will return only the issues which allow unrestricted viewing. That is, 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. Note: This parameter is available only if you insert the macro via wiki markup or by editing the storage format of the page. The graphic user interface (macro browser) for the JIRA Issues macro does not offer this parameter. |
| 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. |
| No | By default, the following columns are shown:
| A list of JIRA column names, separated by semi-colons (;). You can include any columns recognised by your JIRA site, including custom columns. See the JIRA documentation for a list of names. |
| No |
| 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. |
| No |
| 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'.) Note: This parameter is available only if you insert the macro via wiki markup or by editing the storage format of the page. The graphic user interface (macro browser) for the JIRA Issues macro does not offer this parameter. |
| No |
| The height in pixels of the table displaying the JIRA issues.
Note: This parameter is available only if you insert the macro via wiki markup or by editing the storage format of the page. The graphic user interface (macro browser) for the JIRA Issues macro does not offer this parameter. |
| No |
| If the value is 'dynamic', the JIRA Issues macro offers an interactive display which people can manipulate as follows:
A value of 'static' will disable the dynamic display features. Note: This parameter is available only if you insert the macro via wiki markup or by editing the storage format of the page. The graphic user interface (macro browser) for the JIRA Issues macro does not offer this parameter. |
| 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. Note: This parameter is available only if you insert the macro via wiki markup or by editing the storage format of the page. The graphic user interface (macro browser) for the JIRA Issues macro does not offer this parameter. |
| 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 |
| No | 100% | The width of the table displaying the JIRA issues. Can be indicated either as a percentage (%) or in pixels (px). Note: This parameter is available only if you insert the macro via wiki markup or by editing the storage format of the page. The graphic user interface (macro browser) for the JIRA Issues macro does not offer this parameter. |
Example using a URL that points to the XML view of a JIRA search:
<ac:structured-macro ac:name="jiraissues"> <ac:parameter ac:name="anonymous">true</ac:parameter> <ac:parameter ac:name="columns">type;key;summary</ac:parameter> <ac:parameter ac:name="url"> <ri:url ri:value="http://jira.atlassian.com/sr/jira.issueviews:searchrequest-xml/temp/SearchRequest.xml?jqlQuery=project+%3D+CONF+AND+%28summary+%7E+jiraissues+OR+description+%7E+jiraissues+OR+comment+%7E+jiraissues%29&tempMax=10"/> </ac:parameter> </ac:structured-macro>
Example using JQL – note that Confluence will insert the server
and serverId
parameters, based on settings in Application Links:
<ac:structured-macro ac:name="jira"> <ac:parameter ac:name="columns">key,summary,type,created,assignee,status</ac:parameter> <ac:parameter ac:name="server">Atlassian JIRA</ac:parameter> <ac:parameter ac:name="serverId">144880e9-a1111-333f-9412-ed999a9999fa</ac:parameter> <ac:parameter ac:name="jqlQuery">project = CONF AND component = documentation AND resolution = unresolved</ac:parameter> </ac:structured-macro>
{jiraissues:anonymous=true|url=http://jira.atlassian.com/sr/jira.issueviews:searchrequest-xml/temp/SearchRequest.xml?jqlQuery=project+%3D+CONF+AND+%28summary+%7E+jiraissues+OR+description+%7E+jiraissues+OR+comment+%7E+jiraissues%29&tempMax=10|columns=type;key;summary|title=My List of Issues}