General idea - using Jasper Reports with icTime

Prerequisites

• You should have a report design tool to build Jasper Reports jrxml files. We suggest to usen either the standalone Jasper Studio Designer or the Eclipse Plugin to build Jasper reports.
• You should have access to a JIRA Installation with icTime time tracking plugin installed, Version 5.8.2 or later
• We recommend using a copy of your production database while developing reports.

Introduction

icTime expects a zip archive containing all files required to fill and execute a report. The archive must contain a file named main.jrxml. This file is compiled and "filled" during report execution. Usage of style sheets (jrtx files) and Jasper Sub Reports is supported as well, but must meet some conventions to be executable in your target JIRA installation.

Starting point

• Download the examples we provide on our website or install the samples bundled in the plugin. Examples are available for the following databases:
  • MySQL
  • PostgreSQL
  • MSSQL
  • Oracel
• Test the example(s) in your JIRA/icTime installation
• For development of your own reports
  • Unzip and explore the example  filles (download sources from our website)
  • Test main.jrxml file in your Report Designer using the Jasper Reports preview option
  • Rebuild the archive 
  • Deploy your test archive and test it in your Jira/icTime environment

Step by Step Explanation

• Download the source of the sample02: sample02_barchart_ict582-src.zip
• Extract example sample02_barchart_ict582-src.zip

You will get a structure like this:

Files & Usage

Installing samples from the plugin

Samples for all supported databases are shipped with the plugin.

You can install the plugins using the "Install samples Button" from icTime Administration => Custom Reports view

Downloding samples

Direct usable samples (zip files only) - click on zip file to download:

Full source sample files (for developing own reports)

Remarks - Postgres

It is not possible to preview the sample reports in Jasper Studio, due to a missing auto type conversion in psgl. To test report, remove "$X(in,...)" from the where condition in the report while testing. Insert the condition afterwards.

Parameter usage

Supported Parameter Types

The following data types are supported during report execution in JIRA / icTime. 

Report Parameter Data Type	Prompt on execution	Remarks
Long
Integer
BigDecimal		Use "." as decimal delimiter. No grouping supported (e.g. 123500.23)
Date		With Date picker according to your individual date format settings
java.util.Collection	Number values only	Example: Entering 123,125,130 will be converted in a collection. Each value will be converted to a Long

Uploading a report (Custom Reports)

Navigate to ictime / Administration /Custom Reports and click on Create.
The following screen will appear:

Fields & Explainations

Field	Change value allowed after creation?	Description
Name		The name of the report. Will be shown in timesheet / reporting if applicable
Description		Put any meaningfull description in here (e.g. Version of the report, content of the report)
Locale		During execution of the report (on your target system), localization of Dates and numbers will be done using the locale of the target environment by default. If you need a specific locale in the report, than you can use the locale setting here. It is passed as REPORT_LOCALE parameter to the report.
Type
Report result type		Only applicable for report type "general". Defines the target of the report.
Disabled		Once this option is selected, the report will not be shown any longer in timesheet / reporting and is no longer usable for invoicing
Show in reporting		Option to allow/disallow report execution from icTime reporting page
Show in timesheet		Option to allow/disallow report execution from icTime timesheet page

Executing a report

From the Custom Report List

Go to ictime / Administration / Custom Reports.
You will get a list of all Custom Reports available:

Use the "Exec" link in the most right column to run a specific report.

This will show a dialog prompting for the parameters which are defined in the report.

All parameters are displayed in a form using the parameter name as label. Submit the form by pressing the "Execute" button.

Execution from Timesheet or Reporting view

Run a search from the Timesheet or Reporting view. The result of the search is a list of work logs meeting your search criteria. 

Select the report you want to run on the resulting Issues/Work logs from the dropdown "Export (CR)". This will open the report execution dialog. The parameter (worklog_ids) - if defined in the report - is pre-populated with the complete list of work log ids returned by your search.

Sample output:

Working with sub-reports

• How to build jasper files from jrxml in Eclipse
  • Use your report project
  • Remove automatic build:  setting in Project => Build Automatically (uncheck checkbox)
  • Run build all from Project menu - for project reportsIcTime
    • This should build the compiled report files in your reportsIcTime Project. As this is linked to IcTime, you are good!
    • There is no need (never do this) to add compiled files in SVN. Only put source files in there .

Fonts

If you want to use special fonts, we recommend to use a style sheet file to have a single place, where you maintain your font definitions.

Adding fonts to your Server Installation

• Please refer to the documentation provided here http://www.perfectabstractions.com/blog/how-to-install-windows-fonts-in-java-on-linux

Check if a specific font is available in your JIRA Installation

All available fonts are listed below the report list in the icTime => Administration : Tab Custom Reports

Make fonts available to JasperReports - Registration of fonts

Create a font extension including all fonts you require archive usable by JaserReports and provide the jar archive in your Jira Installation directory in the lib subfolder (e.g. /opt/atlassian/jira/lib/).

Structure of the jar extension is:

• jasperreports_extension.properties
  
• yourFontDefintion.xml
• FONT_SUB_FOLDER
  • fontfile_1.ttf
  • fontfile_2.ttf
  • ....

You should NOT use font.xml as font file definion name. This collides (may collide) with the font definiton provided in the default JRE provided by Atlassian.

Contents of jasperreports_extension.properties

net.sf.jasperreports.extension.registry.factory.fonts=net.sf.jasperreports.engine.fonts.SimpleFontExtensionsRegistryFactory
net.sf.jasperreports.extension.registry.factory.simple.font.families=net.sf.jasperreports.engine.fonts.SimpleFontExtensionsRegistryFactory
net.sf.jasperreports.extension.simple.font.families.MyFont=YOUR_FONT_DEFINTION_FILE_NAME

Permissions

Permissions considered for Custom Reports. 

Please find details for administrating permissions here.

Compatibilty

Exchanging the report engine

You may change the reporting engine by changing the the corresponding Jar archive in icTime plugin using a binary compatible version. Support for patched icTime plugins is not be provided.