Customizing the JIRA Report

Note: Most of the features used in this document was introduced in version 2.0 of the Changes Plugin. See the goal documentation for detailed info on which feature was added in which version.

What version of JIRA are you using?

Depending on which version of JIRA you use, you might need to add bits of configuration to make the JIRA Report work properly. Starting with JIRA 5.1 it is no longer possible to ask JIRA questions using query parameters. If you use JIRA 5.1 or newer you must add this configuration, or else you will see a stack trace saying something like "Caused by: org.xml.sax.SAXParseException".

<project>
  ...
  <reporting>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-changes-plugin</artifactId>
        <version>2.12.1</version>
        <configuration>
          <useJql>true</useJql>
        </configuration>
        ...
      </plugin>
    </plugins>
  </reporting>
  ...
</project>

Selecting version(s)

We'll start off by creating a JIRA Report for one or more versions of your project. There are two ways to do this.

Using fix version id(s)

This is the manual way of doing it. You specify one or more fix version ids, separated by commas. The version ids are usually five digit numbers, but that depends on your JIRA installation.

The good thing about this method is that you can specify exactly which versions you want, but you have to remember to update your configuration for every new release that you want to include in the report.

<project>
  ...
  <reporting>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-changes-plugin</artifactId>
        <version>2.12.1</version>
        <configuration>
          <fixVersionIds>13722,12515</fixVersionIds>
        </configuration>
        ...
      </plugin>
    </plugins>
  </reporting>
  ...
</project>

Using the current version

If you are lazy and only ever want the latest release in you JIRA Report, you can use the <onlyCurrentVersion> configuration parameter. It will take the version from your project's POM and try to match it against the "Fix for" version of the JIRA issues.

Once you have configured this, you can forget about it, as it updates itself when you change the version number in your POM.

Note: The names of your versions in JIRA must match the ones you use in your POM. The -SNAPSHOT part of the version in your POM is handled automatically by the plugin, so you don't need to include -SNAPSHOT in the names of your versions in JIRA.

<project>
  ...
  <reporting>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-changes-plugin</artifactId>
        <version>2.12.1</version>
        <configuration>
          <onlyCurrentVersion>true</onlyCurrentVersion>
        </configuration>
        ...
      </plugin>
    </plugins>
  </reporting>
  ...
</project>

Selecting columns

If you are a fan of the Issue Navigator in JIRA, you are going to love this. You can select which columns to include in the report and also specify in which way the issues are sorted.

In this example we have selected a couple of extra columns, that are not included by default. We want the issues sorted by Type first and by Key secondly. The keys will be sorted in descending order thanks to the DESC marker. Normally they are sorted in ascending order.

<project>
  ...
  <reporting>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-changes-plugin</artifactId>
        <version>2.12.1</version>
        <configuration>
          <columnNames>Type,Key,Summary,Assignee,Status,Resolution,Fix Version</columnNames>
          <sortColumnNames>Type,Key DESC</sortColumnNames>
        </configuration>
        ...
      </plugin>
    </plugins>
  </reporting>
  ...
</project>

Filtering issues

Is your report filled with issues that you don't want to publicise? Does it contain duplicate issues and stuff that you decided not to fix? Then this part is for you.

Using Maven syntax

In the following example we are only including issues that have Fixed as their resolution. The status must be either Resolved or Closed. Only issues with one of the types Bug, New Feature, Improvement or Wish are included in the report.

<project>
  ...
  <reporting>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-changes-plugin</artifactId>
        <version>2.12.1</version>
        <configuration>
          <resolutionIds>Fixed</resolutionIds>
          <statusIds>Resolved, Closed</statusIds>
          <typeIds>Bug, New Feature, Improvement, Wish</typeIds>
        </configuration>
        ...
      </plugin>
    </plugins>
  </reporting>
  ...
</project>

You can also filter by <component> and <priorityIds>. See the goal documentation for info on how to use them.

Using JIRA syntax

Another way to filter and sort issues is to configure the plugin using a JIRA syntaxed filter. You can grab this from the URL if you filter and sort issues in the Issue Navigator in JIRA. Just remember that you have to escape the ampersand (&) characters, when you put them into the xml based POM.

In this example we are filtering out issues with Fixed as resolution and sorting them by type, in ascending order.

<project>
  ...
  <reporting>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-changes-plugin</artifactId>
        <version>2.12.1</version>
        <configuration>
          <filter>resolution=1&amp;sorter/field=issuetype&amp;sorter/order=ASC</filter>
        </configuration>
        ...
      </plugin>
    </plugins>
  </reporting>
  ...
</project>