JIRA
Explanation
Everything the JIRA Macros and the JIRA Scripting API display comes from a JIRA instance the wiki connects to. An administrator decides which instances may be reached and under which account, in the "JIRA" section of the wiki administration, following Configure a JIRA Server.
Only a JIRA Server or JIRA Data Center instance can be reached. Jira Cloud is not supported, because the JIRA Macros read the issue search and chart endpoints that only Server and Data Center expose.
An instance is defined once and given a free-form id. Page authors then designate it by that id rather than by its URL, which has two consequences worth understanding. The URL exists in a single place, so moving JIRA to another address means editing one configuration entry instead of every page holding a Macro. And credentials can be attached to the instance, which is what makes issues that are not public displayable at all.
A URL written directly in a Macro is not necessarily read anonymously: the wiki compares it, ignoring a trailing slash, with the URL of every defined instance, and reuses that instance's credentials when one matches exactly. Relying on that is fragile, because a URL that differs in its scheme, its host name or a trailing path segment matches nothing and silently falls back to an anonymous connection.
Instance definitions are stored per wiki, so each wiki of a farm has its own list and its own credentials.
The account configured for an instance is the account every reader of every page is served from. There is no per-reader authentication: the wiki does not know each reader's JIRA identity and never asks for it. Giving an instance a powerful account therefore exposes, to anyone able to view a wiki page, every issue that account can read. Conversely, an account that may not read one issue targeted by a Macro makes the page show an error, as described in JIRA Connection Errors.
Defining instances is the only configuration the JIRA Macros need. Converting a JIRA URL pasted in the WYSIWYG editor is the exception: it comes from a separate extension whose plugin must be declared in the editor configuration.
Authentication itself is pluggable. Basic authentication, in which a username is paired with a password or an API token, is the scheme shipped with the extension; a developer can add another one, and it then appears in the same administration section alongside it.
FAQ
Do I have to configure an instance at all?
No. A page author can point a Macro straight at a JIRA URL, but then the issues are read anonymously and only public ones can be displayed.
Are the credentials shared across the wikis of a farm?
No. Each wiki holds its own instance definitions and its own credentials.
Can readers see the configured password?
No. The credentials are stored in the wiki administration, which only administrators can view, and are never sent to the browser.
Can I stop the JIRA Macros from rendering asynchronously?
Yes. In an XWiki installation the jira Macro renders asynchronously by default, so that a slow JIRA instance does not hold up the rest of the page. Set jira.async=false in xwiki.properties to render it 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.
