How to add a new report or portlet (to the Jira TimeTracking Reporting Collection)

This tutorial will show how to add a new report template.
The same procedure can be used when adding a portlet.

Plugin Version

1. Step - editing timetracking.properties

1. Open the file com/ja/jira/plugin/timetracking/properties/timetracking.properties in a text editor.
2. Add a new key to the property timetracking.report.keys, for instance timetracking_customfield_n_user. Keys are separated by [;]
3. Add 3 new properties:
   

   timetracking.report.name.timetracking_customfield_n_user:timetracking.report.name.timetracking_customfield_n_user
   timetracking.report.file.timetracking_customfield_n_user:com/ja/jira/plugin/timetracking/templates/timetracking_customfield_n_user.vm
   timetracking.report.fileexcel.timetracking_customfield_n_user:com/ja/jira/plugin/timetracking/templates/timetracking_customfield_n_user.vm

   Tip: the 3th property is only necessary if you want an excel version of the report as well.
   

2. Step - editing timetracking_labels.properties

1. Open the file com/ja/jira/plugin/timetracking/properties/timetracking_labels.properties in a text editor.
2. Add 1 new property:

   timetracking.report.name.timetracking_customfield_n_user:My new report

   Notice: My new report will be the name of the report, and you can easily change it. 

3. Step - add a velocity file

Notice: The velocity file decides the design of the report.
Notice: All reports and portlets are respectively instantiated from timetrackingreport.vm and timetrackingportlet.vm
Tip: When designing a new report you are probably better of just to copy/paste an existing file.
Tip: For a detailed instruction on how to use the velocity framework, se this guide, http://velocity.apache.org/engine/devel/user-guide.html

The velocity file most has the same filename and path as used in Step 1.3 for the property timetracking.report.file. timetracking_customfield_n_user, in this example com/ja/jira/plugin/timetracking/templates/timetracking_customfield_n_user.vm (A sample file for this report can be downloaded here)

Notice: That in the sample velocity file you most replace this String customfield_10121 (at line 4), with an ID for a customfield in your Jira instance.

4. Step - Restart

Notice: You most restart Jira.

5. Step - Done! (Did it work?)

The My new report report can now be picked from the Portlet/Report format field from the Report configuration page.

How to add a portlet or a service template instead?

You might have notice that there is two different portlet and two different reports. All are using the same configuration parameters, except for one of the portlets and reports, which also uses a period parameter.

So when adding portlets, reports and service templates we have to difference between these.

In Step 1.2 we added a key to the property timetracking.report.keys. And the key we added we reused in the properties we added in Step 1.3.

When adding a portlet, a period portlet, a period report or a service template we have to do this in a similar way.

Locate one of the following property names:
timetracking.report.keys
timetracking.report.period.keys
timetracking.portlet.keys
timetracking.portlet.period.keys
timetracking.service.keys

Add a new key to one of those properties, like we did in Step 1.2.

Add new properties like we did in Step 1.3. Notice that the key we added to the timetracking.xx.keys property (like in Step 1.2.) most be used as the last token of the new property names.

What we actual do is that we pair the key for the report, a name for the report (portlet or service) and a velocity file that defines the output of the report. The name of the report will be available from the configuration page of the report.

Note that you can use any name as key, or any filename. It's not recommended to use special characters, spaces and so on - Use A-Z, a-z and 0-9.