This feature is available for ictime version 5.2 and higher. |
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.
Custom reports offer unlimited flexibility - but this is not an out-of-the-box solution for non-technical users. You build your own reports, and need to be able to create reports with JasperReports tools - or you will need to contract someone who knows this technology and can code reports for you. In addition, you will need to understand the database structure of ictime (and/or JIRA and/or other add-ons) as far as required to know where data is located and how it is related. |
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.
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.
We have already created some reports that you can use as a starting point for your reports:
English (MySQL) | German (MySQL) | English (PostgreSQL) | English (MsSql)1 | |
---|---|---|---|---|
Invoice | Download | Download | Download | |
Credit note | Download | Download | Download | Download |
Invoice (Service Level Agreement) | Download | Download | Download | |
Credit note (Service Level Agreement) | Download | Download | Download |
1 MsSql Database schema must be "jiraschema". In case your JIRA database is running using a different schema, reports need to be adapted.
You can use e.g. one of the following tools to create your report:
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.
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).
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"/>
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.
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.
Currently not supported.
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).
Only .zip files can be uploaded to ictime, other formats are not supported. It does not matter if your report only consists of one file or also includes image data. |
Field | Description | Remarks | ||
---|---|---|---|---|
Name | Name for the report. | Mandatory | ||
Description | Short description for the report. | Optional. | ||
Locale | E.g en_US, de_DE, es_ES. Set this, if you want to change settings like the decimal or thousands separator in the report. If not set, the system/Java default will be used. | Optional. | ||
Type | The type is used to distinguish normal reports from reports used as templates for invoices and credit notes (in case you have enabled the invoice documents feature, see General Configuration).
If you have chosen INV_BILL or INV_CRN as type, you can't change this selection any longer after you have saved the report. In addition, you can't delete reports with this type any longer once they have been used for at least one invoice. | Mandatory. Default is GENERAL. | ||
Permission | NOT IMPLEMENTED | |||
Disabled | Option to disable the report. | In case you can't delete a report any longer (this is the case for reports that have been used as invoice templates), you can deactivate it. This report won't appear any longer in dropdowns or lists (for normal users, users with a permission to manage reports q´will still see the report) | ||
File | Option to upload your report file. Needs to be a .zip file and this file needs to contain your report in .jrxml format and with the file name main.jrxml.
| Shows the data directory (something like: /var/atlassian/application-data/jiratest/data/ictime/reports). Please ensure that ictime can write in this directory. |
Field | Description | Remarks |
---|---|---|
Name | Name for the report. Can be changed. | Mandatory |
Description | Short description for the report. Can be changed. | Mandatory |
Type | If you have chosen INV_BILL or INV_CRN as type, you can't change this selection any longer after you have saved the report. If you have chosen GENERAL, you can still change this to INV_BILL or INV_CRN. | Mandatory. |
Permission | NOT IMPLEMENTED | |
Disabled | Option to disable the report. | In case you can't delete a report any longer (this is the case for reports that have been used as invoice templates), you can deactivate it. This report won't appear any longer in dropdowns or lists (for normal users, users with a permission to manage reports will still see the 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.
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.
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:
Normal reports frequently contain parameters in order to let a user insert or select data when a report is executed. For invoices, this is neither required nor will it be used during the invoicing process, all parameters will be ignored. As part of the invoicing process, all data required will be provided via the invoice mask. However, it might make sense to define at least a parameter for the invoice ID for testing purposes (to see if a new report works, you do not need to create a new invoice, but just execute the respective report with the ID of an existing invoice). |
Reference Table for data fields that are available in the invoice dataset:
Field | Description | Remarks |
---|---|---|
Please note that you are not limited to these fields when creating a template for invoices or credit notes.
Field | Description | Remarks |
---|---|---|
Name | Name for the report. | |
Description | Short description for the report. | |
Type |
| |
Permission | NOT IMPLEMENTED | |
Disabled | false/true |
Custom reports do not implement a default security concept to limit data that can be retrieved and displayed by a report. This means that a user who can run a report gets access to all data that is displayed by this report, even if this data would not be accessible for the user when using the JIRA user interface. |
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.
It is not possible to execute queries in a report that are modifying the data source, i.e. only SELECT queries will be executed. |
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.
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.
Install the Font as system font on your JIRA Server
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.