JIRA
Explanation
The JIRA integration displays issues stored in a JIRA instance inside wiki pages. The issues are fetched when the page is displayed, so a page never holds a copy of the issue data that goes stale.
Which issues are displayed is decided in one of two ways: an explicit list of issue keys, or a JQL query evaluated by JIRA. Either one is written in the content of a JIRA Macro, and the Macro parameters decide which JIRA instance is queried and how the result is presented.
The JIRA instance is designated either directly by its URL, with the url parameter, or by an id that an administrator has given it in the wiki administration, with the id parameter. Using an id is preferable, for the reasons given in JIRA administration, which also states which JIRA versions can be reached and under which account.
Four different goals are covered, each by its own Macro, and choosing between them is mostly a question of what you want the reader to see:
- Display JIRA Issues in a Page, to render a set of issues as a table, a bulleted list or an enumeration, when the reader needs the issues themselves
- Count JIRA Issues in a Page, to display only the number of issues matching a query, when the count is the information and the issues are noise
- Display a JIRA Chart in a Page, to show JIRA's own aggregated statistics as a pie chart, a created-versus-resolved chart or a bidimensional grid, when the reader needs a trend or a distribution rather than individual issues
- Paste a JIRA URL to Insert a JIRA Macro, to have any of the above inserted for you, which is the fastest route when you already have the issue or search open in your browser
Everything the Macros can display is subject to what the account the wiki uses to reach JIRA is allowed to see. When that account may not read an issue a Macro selects, the Macro displays an error in place of the issues, as described in JIRA Connection Errors.
FAQ
Do I need a JIRA account to see the issues in a page?
No. The wiki reaches JIRA anonymously, or with the single account an administrator configured for that instance, so every reader of the page sees the same issues.
Are the issues fetched again every time the page is displayed?
Yes, the result is not cached, which is what keeps it up to date. In an XWiki installation the fetch also happens asynchronously by default, so a slow JIRA instance does not hold up the rest of the page; an administrator can render the Macros synchronously instead.
More
To find more about the current topic, you can search or use the table below and filter the columns to narrow your choices.
