JIRA Macro

Fetches information from a JIRA server and displays them as a table, list or enumeration

Description

Fetches information from a JIRA server and displays them as a table, list or enumeration.

Usage

where:

Parameter Name	Mandatory?	Default Value	Description
url		N/A	URL to your JIRA server. (example: http://jira.xwiki.org)
source		list	Defines how the list of JIRA issues is specified. Allowed values: list and jql. With the list value, the user must specify a discrete list of JIRA issue ids in the macro content, one per line. The user can also specify a Note separated by the pipe symbol from the Issue key. With the jql value, the user specifies a JQL Query in the macro content.
style		table	Specifies the way you want the results displayed. Allowed values are table, list and enum
fields		table type, key, status, summary, created list status, key, summary enum status, key	Specifies the fields you want to display for each JIRA issue. If not defined then uses the defaults which depend on the style defined.
fieldNames		Field Name summary Summary key Key type Type status Status assignee Assignee reporter Reporter created Created Date updated Updated Date resolved Resolved Date fixVersion Fixed In component Component votes Votes resolution Resolution link Link version Affected Versions	Overrides the field names. This is used only by the table style, in case you want custom field names, or if you want to internationalize your macro.

The list of valid JIRA fields can be found on the JIRA Advanced Searching page. In addition we've added a note field which corresponds to the notes you can add as part of the macro content when using a list source (see the example below).

Examples

• JIRA Macro using defaults:
  {{jira url="http://jira.xwiki.org"}}
  XWIKI-2484
  XE-291
  XWIKI-3677
  {{/jira}}

  

• JIRA Macro as Table using custom fields and custom field names:
  {{jira url="http://jira.xwiki.org" style="table" fields="type, key, summary, status, assignee, created, note" fieldNames="'Issue type', 'Issue Id', 'Short Description', 'Issue Status', 'Person to Fix this', 'Creation Date', 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}}

  

• JIRA Macro as List with default fields:
  {{jira url="http://jira.xwiki.org" style="list"}}
  XWIKI-2484
  XE-291
  XWIKI-3677
  {{/jira}}

  

• JIRA Macro as Enum with default fields:
  {{jira url="http://jira.xwiki.org" style="enum"}}
  XWIKI-2484
  XE-291
  XWIKI-3677
  {{/jira}}

  

• JIRA Macro as Table using JQL with default fields:
  {{jira url="http://jira.xwiki.org" style="table" source="jql" }}
  (project in (XWIKI) and fixVersion in ("3.2 M1", "3.2 M2", "3.2 M3", "3.2 RC1", "3.2")
  and resolution in ("Fixed")) or (project in (XE)
  and fixVersion in ("3.2 M1", "3.2 M2", "3.2 M3", "3.2 RC1", "3.2")
  and resolution in ("Fixed")) or (project in (XRENDERING) and fixVersion in ("3.2 M1", "3.2 M2", "3.2 M3", "3.2 RC1", "3.2")
  and resolution in ("Fixed")) or (project in (XCOMMONS) and fixVersion in ("3.2 M1", "3.2 M2", "3.2 M3", "3.2 RC1", "3.2")
  and resolution in ("Fixed")) or (project in (XEM) and fixVersion in ("3.2 M1", "3.2 M2", "3.2 M3", "3.2 RC1", "3.2"))
  {{/jira}}

  

Extensibility

There are 3 ways to extends the Macro:

• Add a new Style. You'll need to write a Component and implement the org.xwiki.rendering.macro.jira.JIRADisplayer interface:
  @Role
  public interface JIRADisplayer
  {
     /**
       * Displays the passed JIRA issues.
       *
       * @param issues the issues to display
       * @param parameters the macro parameters specified by the user; can be used to specify displayer-specific
       *        configuration data (for example displayers allows the user to specify the list of JIRA issue fields to
       *        display
       * @return the list of Blocks rerpesenting what to display
       */
      List<Block> display(Collection<Element> issues, JIRAMacroParameters parameters);
  }
• Add a new Source. You'll need to write a Component and implement the org.xwiki.rendering.macro.jira.JIRADataSource interface:
  @Role
  public interface JIRADataSource
  {
     /**
       * @param macroContent the macro content which contains the source definition
       * @param parameters the macro parameters which can contain source-specific configuration information
       * @return the list of matching JIRA issues
       * @throws MacroExecutionException in case of an error while getting the JIRA data
       */
      Collection<Element> getData(String macroContent, JIRAMacroParameters parameters)
         throws MacroExecutionException;
  }
• Add new Field Displayers. For each field for which you wish to have a custom field displayer, you'll need to write a Component, implement the org.xwiki.rendering.macro.jira.JIRAFieldDisplayer interface and use a Role being the field name:
  @Role
  public interface JIRAFieldDisplayer
  {
     /**
       * Generate Blocks to display the passed field.
       *
       * @param fieldName the name of the field to display
       * @param issue the JIRA issue as an XML element, can be used to extract information useful to generate the display
       * @return the list of Blocks to display the passed field
       */
      List<Block> displayField(String fieldName, Element issue);
  }

Prerequisites & Installation Instructions

Put the jar file into WEB-INF/lib folder and restart XWiki.

Dependencies

• org.xwiki.rendering:xwiki-rendering-api 5.0.3
• org.jdom:jdom2 2.0.4
• org.xwiki.commons:xwiki-commons-component-api 5.0.3
• org.xwiki.rendering:xwiki-rendering-transformation-macro 5.0.3