"jira" Macro
Reference
Description
Fetches issues from a JIRA instance and displays them as a table, a bulleted list or an enumeration. The issues are either listed explicitly by their key in the Macro content, or selected by a JQL query.
Only the enum style can be used inline, inside a sentence; table and list always start a new block. How and when the issues are fetched is described in JIRA for users.
Usage
The Macro content holds either one issue key per line, when source is list, or a JQL query, when source is jql. With the list source a key may be followed by a pipe character and a free-text note, which the note field displays.
{{jira id="..." url="..." source="..." style="..." fields="..." parameters="..." maxCount="..."}}
...the JIRA issues to retrieve...
{{/jira}}Either id or url must be set; id is recommended, for the reasons given in JIRA administration.
Parameters
| Name | Mandatory | Allowed Values | Default Value | Description |
|---|---|---|---|---|
| id | id or url | An instance id defined in the wiki administration | N/A | The JIRA instance to query. Recommended over url, because the URL is then defined in a single place and the instance can authenticate. |
| url | id or url | A JIRA instance URL | N/A | The JIRA instance to query, given directly by its URL. Takes precedence over id when both are set. |
| source | No | list, jql | list | How the Macro content designates the issues. With list the content holds one issue key per line; with jql it holds a JQL query. |
| style | No | table, list, enum | table | How the issues are rendered. Only enum can be used inline, inside a sentence. |
| fields | No | A comma-separated list of field definitions | Depends on style | The issue fields to display, in display order. The defaults are type, key, summary, status, created for table, status, key, summary for list, and status, key for enum. See JIRA Issue Fields for the available ids, the field types, and the id:label!type syntax. |
| parameters | No | A comma-separated list of name=value pairs, values optionally single-quoted | N/A | Configuration passed to the data sources, displayers and field displayers, for example field.url.label='See the issue' to set the label of the links produced by the url field type. Separate several pairs with a comma; any other separator makes the whole value be read as a single pair. |
| maxCount | No | A positive number, or -1 | -1 | The highest number of issues to display. With -1 the limit is the one JIRA applies. |
| fieldNames | No | A comma-separated list of labels | N/A | Deprecated, and used only by the table style: overrides the column headers, positionally. Set the label part of each fields entry instead. |
Examples
Listing issue keys, with the default table
{{jira url="https://jira.xwiki.org"}}
XWIKI-2484
XE-291
XWIKI-3677
{{/jira}}
Displaying a custom JIRA field under a chosen column header
{{jira url="https://jira.xwiki.org" source="jql" fields="type,key,status,'Flickering Test':'List of flickering tests'"}}
"Flickering Test" is not empty
{{/jira}}
Adding a note to each issue
{{jira url="https://jira.xwiki.org" fields="type:'Issue type', key:'Issue Id', summary:'Short Description', status:'Issue Status', assignee:'Person to Fix this', created:'Creation Date', note:'Notes'"}}
XWIKI-2484|Hard to fix
XE-291|Easy to fix
XWIKI-3677|This issue takes too long. Need to find a solution ASAP
{{/jira}}
Rendering the issues as a bulleted list
{{jira url="https://jira.xwiki.org" style="list"}}
XWIKI-2484
XE-291
XWIKI-3677
{{/jira}}
Rendering the issues as an enumeration
{{jira url="https://jira.xwiki.org" style="enum"}}
XWIKI-2484
XE-291
XWIKI-3677
{{/jira}}
Selecting the issues with a JQL query
{{jira url="https://jira.xwiki.org" style="table" source="jql"}}
project = XWIKI AND resolution = Fixed AND fixVersion = "17.10.0" ORDER BY priority DESC
{{/jira}}
Displaying the labels of each issue
{{jira url="https://jira.xwiki.org" fields="type,key,labels" source="jql"}}
project = XWIKI AND created > 2024-01-01 AND labels IS NOT EMPTY AND resolution = Unresolved ORDER BY priority DESC, updated DESC
{{/jira}}
FAQ
Why is one column empty for some issues?
The field exists on those issues but has no value in JIRA, or the account the wiki uses to reach JIRA cannot read it. A field id that JIRA does not know at all produces an empty column for every issue.
Can I reuse the same issue list with a different presentation?
Not from a single Macro call: each call renders one style. Write a second jira Macro call with the same content and a different style.
