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.

If you need to connect to a JIRA instance that requires authentication, you'll need to install the JIRA Administration extension and configure some JIRA server id in there, which you can then specify using this macro's id parameter (see below).

Usage

where:

Parameter Name	Mandatory?	Default Value	Description
id	or url	N/A	Since 8.2 Configuration id of the JIRA server as defined using the JIRA Administration. This is recommended over using the url parameter for 2 reasons: it's a more flexible solution (for example if you change the JIRA URL one day, you'll need to change it only in one place without having to change all the jira macro calls). it supports authenticating to a JIRA instance
url	or id	N/A	URL to your JIRA server. (example: https://jira.xwiki.org). When specified, takes precedence over the id parameter if also specified. This parameter is mostly kept for backward-compatibility and in general it's recommended to use the id (see the documentation of the id parameter above).
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 ids of the fields you want to display for each JIRA issue. If not defined then uses the defaults which depend on the style defined. Since 8.3 Custom JIRA fields are supported and are specified using their display name. The new format is id:label!type,... where: id: The id of the field. There's a special field named note that can be used when using a List source to add notes to issues (see example below). label: (optional) Replaces the now deprecated fieldNames parameter. It is used by the table style as the display value for the field in the table header. Useful to customize field names, or if you want to internationalize your macro. type: (optional) Specifies an explicit type for the field. This is used when no specific displayer exists for the field, in which case a displayer specific to the specified type is used. When no displayer exist, a default text displayer is used (the field value is then displayed as is with no special formatting). By default 2 type displayers are provided: url (creates a link on the field value that is considered as a URL) and html (consider that the field value is HTML and inject that HTML as the displayed value for the field).
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	Deprecated in 8.3 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.
parameters		N/A	Since 8.3 Specifies parameters for the various sources, displayers and field displayers. For example the url field displayer type supports the field.url.label parameter to customize the label of the link for link values.
maxCount		Defined in JIRA	Since 8.4 the maximum number of JIRA issues to display.

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="https://jira.xwiki.org"}}
  XWIKI-2484
  XE-291
  XWIKI-3677
  {{/jira}}

  

• JIRA Macro as Table using a custom field ("Flickering Test") and a custom field name:
  {{jira url="https://jira.xwiki.org" source="jql" fields="type,key,status,'Flickering Test':'List of flickering tests'"}}
  "Flickering Test" is not empty
  {{/jira}}

  

• JIRA Macro as Table using a custom Note:
  {{jira url="https://jira.xwiki.org" style="table" 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}}

  

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

  

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

  

• JIRA Macro as Table using JQL with default fields:
  {{jira url="https://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}}

  

Troubleshooting

If you get an error such as: Server returned HTTP response code: 400 for URL: [...] this usually means that you there's at least one JIRA issue that requires some permission that user used by the JIRA Macro doesn't have (typically this can happen if you've set some confidential issues). Make sure to use a user that can view all issues.

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.contrib.jira.macro.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.contrib.jira.macro.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.contrib.jira.macro.JIRAFieldDisplayer interface and use a Role being the field name:
  @Role
  public interface JIRAFieldDisplayer
  {
     /**
       * Generate Blocks to display the passed field.
       *
       * @param field the field to display
       * @param issue the JIRA issue as an XML element, can be used to extract information useful to generate the display
       * @param parameters the macro parameters which can contain field displayer-specific configuration information
       * @return the list of Blocks to display the passed field
       */
      List<Block> displayField(JIRAField field, Element issue, JIRAMacroParameters parameters);
  }

Since 8.3 Sources, Displayers and Field Displayers can support configuration parameters defined in the passed JIRAMacroParameters variable type. A best practice is to follow these conventions:

• source.<hint>.* for JIRADataSource parameters
• field.<hint>.* for JIRAFieldDisplayer parameters. For example field.url.label
• display.<hint>.* for JIRADisplayer parameters

Example using a wiki component

Custom Source, Displayer, and Field Displayers are XWiki Components and as such can be developed in Java but also as wiki components in wiki pages as shown below.

This example contributes a new field type named lien that displays a JIRA value as a link with a custom label of Lien.

1. Create a page XWiki.LienJIRAFieldDisplayer (the page can be named as you wish) and add an XWiki.ComponentClass xobject in it:

   
   Note that since we want to add a new field type, the component hint has to be of the form type/<field type>, such as type/lien.

2. We want a dependency on the default org.xwiki.contrib.jira.macro.JIRAFieldDisplayer component implementation in order to access the JIRA field value. Thus we add a XWiki.ComponentDependencyClass xobject:

   

3. Last, we need to implement the component code, i.e. the displayField(...) method:

   

   Source code (so that you can copy-paste it if you need to):

   {{groovy}}
   import org.xwiki.rendering.block.*
   import org.xwiki.rendering.listener.reference.*
   
   def field = xcontext.method.input.get(0)
   def issue = xcontext.method.input.get(1)
   String text = xcontext.method.defaultDisplayer.displayField(field, issue).get(0).getProtectedString()
   
   def reference = new ResourceReference(text, ResourceType.URL)
   def labelBlocks = [new WordBlock("Lien")]
   xcontext.method.output.value = [new LinkBlock(labelBlocks, reference, true)]
   {{/groovy}}

   Note the xcontext.method.defaultDisplayer notation which accesses the component defined in the previous step above. The returned method value is defined using the xcontext.method.output.value call.

Example using the new field type:

JIRA Integration

In addition to this macro you can also find documentation on how to integrate with JIRA at the following places:

• JIRA REST Integration
• JIRA Integration

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager).

You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.

Release Notes

v8.6.1

v8.6

v8.5.2

v8.5.1

v8.5

v8.4.1

v8.4

v8.3

v8.2.1

v8.2

Dependencies

Dependencies for this extension (org.xwiki.contrib.jira:jira-macro-platform 8.6.2):

• org.xwiki.contrib.jira:jira-macro-default 8.6.2
• org.xwiki.platform:xwiki-platform-rendering-async-default 11.10
• org.xwiki.contrib.jira:jira-config-ui 8.6.2