Scope

ictime already provides a powerful reporting functionality that - apart from creating reports - is also used as starting point to charge work logs and create invoice documents (see Reporting and Charge Work Logs - Create Invoice). However, there are practical and technical limits for this functionality, as many customers have specific needs and there is no way to add all features without impacting usability and speed. So we have decided to create a completely independent custom reporting feature where customers can simply create all kinds of reports they need, using a proven standard technology, JasperReports. These custom reports are not limited to ictime data, but might include all data from JIRA or other JIRA add-ons.

Technology

Custom Reports are based on the JasperReports Library. The JasperReports Library is the world's most popular Open Source reporting engine. It is written in Java and it is able to use data from any kind of data source and generates documents that can be viewed, printed or exported in a variety of document formats including HTML, PDF, Excel, OpenOffice or Word (note: starting with version 5.8.2, ictime  supports MS-Excel and PDF format). For more information, refer to http://community.jaspersoft.com/project/jasperreports-library.

Create Reports

Overview

In order to use a report in ictime, you first have to create this report with respective JasperReports tools, have to package/zip it with additional data (like images) and then you can create the report in ictime.

For additional information, please also consider reading Custom Reports enhanced.

Examples of reports for accounting

We have already created some reports that you can use as a starting point for your reports:

^{1 MsSql Database schema must be "jiraschema". In case your JIRA database is running using a different schema, reports need to be adapted.}

Create the Report

Basics

You can use e.g. one of the following tools to create your report:

• http://community.jaspersoft.com/project/jaspersoft-studio
• http://community.jaspersoft.com/project/ireport-designer

JasperReports supports scripting languages like Groovy avoiding the complexity experienced by report writers that don't know Java. However, at this moment, ictime only supports reports that use Java, Groovy is not supported.

File Name

The .jrxml file must be named "main.jrxml", otherwise it won't work (als you will provide your file in a .zip archive that can be named according to your needs, it does not matter that the name needs to be the same for different reports).

Parameters

Usually, before running a report, the user should enter or select data. Define respetive parameters, and the user will be prompted to enter/select the respective information:

Example:

<parameter name="invoiceId" class="java.lang.Integer"/>

Image Files

Ensure that references to images are relative to the report file and do not point e.g. as absolute path to your development system. Images should be located in the same directory as the report file itself.

Fonts

Do only use fonts that are available on your target system. Consider to embed fonts so that users who do not have a font are still able to view the report correctly.

Sub-Reports

Currently not supported.

Package and Provide as .zip File

To upload your report, you need to provide it (with additional files, like images, if applicable) in one .zip file. In this .zip file, you need to provide the non-compiled main.jrxml file (not the compiled .jasper file).

Create Report/Upload Report File/s

Create Report

Edit Report

Note that you can't change the report file/s when editing a report. If you want to change the file, you need to delete or disable the report and create a new one.

Delete Report

Normal reports can be deleted at any time. You can't delete reports with type INV_BILL or INV_CRN any longer once they have been used for at least one invoice.

Templates for Invoices and Credit Notes

As already mentioned above, custom reports are also used to manage templates for the invoicing process (invoices and credit notes). Before you activate the invoice documents feature (see General Configuration), you need to create at least one template for an invoice and one for a credit note.

For invoice and credit note templates, keep the following in mind:

• Charging work logs is a defined process in ictime, and during this process, data is written into the invoice dataset and the so called invoice item datasets as result of this process. All "chargeable" work logs included in the invoice change their status to "charged" in ictime. However, ictime does not define how you invoice document looks like in terms of data, and you are free to add data not only from the invoice and invoice item datasets, but also from any other place in ictime or JIRA or JIRA add-ons. So it is basically your template that defines the business logic and content of your invoice.
• You might need to create multiple templates if you want to reflect different scenarios for invoicing (like e.g. a simple invoice without details, an invoice with details, an invoice with a contingent of hours, an invoice with a fixed fee for a contract and so on). All active templates will be available when you create an invoice, and by choosing the template during the invoicing process, you decide "how" to invoice.
• Credit note templates should reflect the logic of the invoice template exactly - basically it is the same template, only with a different headline and a different source for the document date. If you use multiple invoice templates, you should also create multiple credit note templates. This is not strictly mandatory, but recommended, otherwise the recipient of the credit note might be confused.

Reference Table for data fields that are available in the invoice dataset:

Please note that you are not limited to these fields when creating a template for invoices or credit notes.

Report List

Run Reports

Security Hints

Execute a Report

Normal Reports (Reporting Purposes)

Run a report by clicking the respective icon.

If the report has parameters defined, you will be prompted to enter/select respective values.

Although JasperReports supports a variety of document formats including HTML, PDF, Excel, OpenOffice and Word, at this moment, ictime only supports PDF as output format. We will implement support for other formats in one of the next releases.

Invoice Templates (Invoices, Credit Notes)

If you have added parameters to your template (like invoice ID), you will also be able to "run" the template like any other report. This is only useful for testing purposes, and should never be used to "create" an existing invoice "again". To cover basic requirements of a consistent and reliable accounting system, an invoice can only be created once, and this invoice can only be modified by cancelling the invoice and generating a new one.

Using Fonts

Usage of fonts in reports is limited to the fonts installed as system fonts on your JIRA server. You can check the installed fonts on your JIRA server using fc-list (Linux systems). 

If you want to use Custom Fonts in your reports which are NOT available on your JIRA Server than you have to make them available on the JIRA server.

Option 1 - System Font:

Install the Font as system font on your JIRA Server 

Option 2 - Font Extension:

If you are using the Font Extension from JasperReports, you need to add the .jar File to the lib directory of your JIRA Installation (default directory on Linux Systems: /opt/atlassian/jira/lib/). The font will be available after you restarted the server. You need to redo this step when you upgrade your JIRA installation.