Wiki source code of JIRA
Last modified by Vincent Massol on 2026/08/04 21:49
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | The JIRA integration is assembled out of Components, and every step of the ##jira## Macro's pipeline is one of them. The ##source## parameter selects the Component that turns the Macro content into a set of issues, the ##style## parameter selects the one that turns those issues into rendered blocks, and each field is rendered by the Component registered for its id or, failing that, for its type. Extending the Macro therefore means contributing a Component, never editing a switch: registering one under a new hint is enough to make a new source, a new style or a new field renderer available to page authors. | ||
| 2 | |||
| 3 | {{plantuml}} | ||
| 4 | @startuml | ||
| 5 | !theme bluegray | ||
| 6 | skinparam componentStyle rectangle | ||
| 7 | |||
| 8 | component "**JIRADataSource**\nhint = source parameter\nlist, jql" as DS | ||
| 9 | component "**JIRADisplayer**\nhint = style parameter\ntable, list, enum" as DISP | ||
| 10 | component "**JIRAFieldDisplayer**\nhint = field id, else type/<field type>" as FIELD | ||
| 11 | component "**JIRAMacroTransformation**\nmatched on the parameter type" as TRANS | ||
| 12 | component "**JIRAAuthenticatorFactory**\nhint = authentication scheme id\nbasicauth" as AUTH | ||
| 13 | |||
| 14 | [jira Macro] --> DS : Macro content | ||
| 15 | DS --> DISP : issues | ||
| 16 | DISP --> FIELD : one call per field | ||
| 17 | FIELD --> TRANS : rendered blocks | ||
| 18 | TRANS --> [Page] | ||
| 19 | AUTH ..> DS : signs the request to JIRA | ||
| 20 | @enduml | ||
| 21 | {{/plantuml}} | ||
| 22 | |||
| 23 | Two further extension points sit outside that pipeline. A transformation Component runs after any of the JIRA Macros has produced its blocks and may rewrite them, which is the way to post-process a rendering without reimplementing the Macro. An authenticator Component defines how requests to a JIRA instance are signed, which is the way to support a scheme other than the Basic authentication shipped with the extension. All five roles, with the hints they are looked up under, are listed in [[JIRA Macro Extension Points>>doc:documentation.extensions.dev.jira.extension-points.WebHome]]. | ||
| 24 | |||
| 25 | Components can be written in Java and packaged as a JAR, or written in a wiki page as a Wiki Component, which is the quickest route for a field renderer and needs no build; [[Add a JIRA Field Displayer as a Wiki Component>>doc:documentation.extensions.dev.jira.add-field-displayer.WebHome]] builds one step by step. An authenticator is the exception and needs a JAR, as [[Extend JIRA Authentication>>doc:documentation.extensions.dev.jira.extend-authentication.WebHome]] shows. | ||
| 26 | |||
| 27 | When the goal is not to change how issues are displayed but to reach JIRA from your own code, the [[JIRA Scripting API>>doc:documentation.extensions.dev.jira.scripting.WebHome]] hands you Atlassian's own Java client instead, already pointed at a configured instance. |
