Starting from Reporting version 6.0.0, RandomBits Plugins have been consolidated into a new compile-time library for Reporting and other ServiceRocket add-ons. Due to this major change, developers who previously developed custom reporters for use with Reporting will need to make some changes.

This tutorial will take you to step by step through the process of creating your first Custom Reporter. By the end of this tutorial, you will be able to provide data from your plugin to be displayed in Reporting macro.

Step-By-Step Guide

Step 1: Create Your Plugin Project

If you haven't already done so, go ahead and open a terminal window and do the following:

1. Create a directory under your home directory and navigate to the directory.
    

2. Once you are in the directory, enter the atlas-create-confluence-plugin command to create the plugin.

   atlas-create-confluence-plugin 

3. The command prompts you with the basic information each plugin needs.

   Confirm properties configuration:
   groupId: com.servicerocket.confluence.plugin
   artifactId: custom-reporter
   version: 1.0-SNAPSHOT
   package: com.servicerocket.confluence.plugin

Step 2: Add Reporting Add-on As Dependency

1. Download the obr for Reporting version 6.6.0 from the Atlassian Marketplace.
    
2. Extract the jar file from the obr using your preferred file extraction tool, such as 7-zip or WinRar.
    

3. Install the extracted reporting-confluence-plugin-6.6.0.jar to your local Maven repository using one of the following commands:

   mvn install:install-file \
   -Dfile=<path-to-reporting-jar-file>/reporting-confluence-plugin-6.6.0.jar \
   -DgroupId=com.servicerocket.confluence \
   -DartifactId=reporting-confluence-plugin \
   -Dversion=6.6.0 \
   -Dpackaging=jar

   or

   mvn install:install-file -Dfile=<path-to-reporting-jar-file>/reporting-confluence-plugin-6.6.0.jar

4. Next, add the Reporting add-on as a dependency to your plugin's pom.xml:

   <dependency>
       <groupId>com.servicerocket.confluence</groupId>
       <artifactId>reporting-confluence-plugin</artifactId>
       <version>6.6.0</version>
       <scope>provided</scope>
       <exclusions>
           <exclusion>
               <groupId>*</groupId>
               <artifactId>*</artifactId>
           </exclusion>
       </exclusions>
   </dependency>
   <dependency>
       <groupId>com.servicerocket.confluence.plugin</groupId>
       <artifactId>servicerocket-utility-library</artifactId>
       <version>2.2.0</version>
       <scope>provided</scope>
   </dependency>

Step 3: Component Import Plugin Modules

Import the required Java components into your plugin by adding the following lines into atlassian-plugin.xml:

<component-import key="reportingMacroAssistant" interface="net.customware.reporting.confluence.ReportingMacroAssistant" />
<component-import key="licenseChecker" interface="net.customware.reporting.confluence.license.LicenseChecker" />

Step 4: Create Custom Reporter Class

1. Create a Query object by extending AbstractSortableQuery<T> where T is the type of object in your individual results.
    

2. Create the reporter macro by extending AbstractReporterMacro<T> (same T as above).
   The reporter superclass assumes a rich text body that will be evaluated.
   It is possible to override it to plain text but you will need to override the report() method as well.
   For example:

   @Override
   protected String report(MacroInfo info) throws MacroExecutionException, ReportException {
       Queryable<? super MyClass> queryable = getReportingAssistant().getQueryable(MyClass.class);
       if (queryable == null) {
           throw new MacroExecutionException("This reporter cannot be used in this context.");
       }
       Query<? extends MyClass> query;
       try {
           query = createQuery(info);
       } catch (QueryException e) {
           throw new MacroExecutionException(e);
       }
    
       queryable.addQuery(query);
       return "";
   }

3. Lastly, you may register the Reporter macro like any other xhtml-macro.