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.
You will get a structure like this:
File | Purpose | Remarks |
---|---|---|
build_sample02.sh | Build file (Linux) to create the executable Report archive (ictime_sample02.zip) | Steps done by build_sample02.sh:
|
iconcept_log.png | The picture (corporate logo) used in the report | |
ictime_sample02.zip | The ready to run zip Archive | Ready to upload report zip archive |
jr_sample_styles_ic_v10.jrtx | Sample style sheet file used in the main report file | |
main_sample02.jasper | Compiled version of main_sample02.jrxml | |
main_sample.jrxml | Main report file | Features used:
|
icTime expects the main report file to be saved as "main.jrxml" in the zipped report archive. On linux systems you can use the build script (build_sample_xx.sh) to create your archive. |
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
Direct usable samples (zip files only) - click on zip file to download:
Name | Description | for MySql | Postgres | MsSql | Oracle |
---|---|---|---|---|---|
sample01 | Report, using sub reports to show time worked by
| Sample 01 (mysql) | Sample 01 (postgres) | Custom Report Sample 01 (MsSql) | Sample 01 (Oracle) |
sample02 | Report, showing time worked grouped by user and day | Sample 02 (mysql) | Sample 02 (postgres) | Custom Report Sample 02 (MsSql) | Sample 02 (Oracle) |
Name | Description | for MySql | Postgres | MsSql | Oracle |
---|---|---|---|---|---|
sample01 | Report, using sub reports to show time worked by
| Sample 01 MySql | Sample 01 Postgres | Sample 01 MsSql | Sample 01 Oracle |
sample02 | Report, showing time worked grouped by user and day | Sample 02 MySql2 | Sample 02 Postgres | Sample 02 MsSql |
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 name | Purpose | JRXML-Source code |
---|---|---|
EXEC_DIRECTORY_hidden | Populated during execution from icTime (no action needed by the user). Contains the directory where the report is executed | <parameter name="EXEC_DIRECTORY_hidden" class="java.lang.String"> |
worklog_id | Contains the list (Collection of Integers) when executed from Timesheet or Reporting. This list will be automatically provided by icTime base on the selection you run your Reporting. | <parameter name="worklog_ids" class="java.util.Collection"> |
SUBREPORT_DIR | If present and empty: icTime populates parameter with directory where the report is executed.
|
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 |
Navigate to ictime / Administration /Custom Reports and click on Create.
The following screen will appear:
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 |
To be able to execute any report, you need either to have the Custom Report administration permission OR at least the Custom Report execution permission. |
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.
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.
If you want run a Custom Report in a specific context like ictime Reporting or Timesheet, please process in this order: Apply your filters, run your query (i.e. in Reporting by "Create Report") and then trigger your Custom Report via click on "Export (CR)" (available only if Custom Reports are available/installed, works with sample reports). |
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.
The font you are using on your report design system (if this differs from your production machine) may NOT be available in the JIRA / icTime execution environment. If the font is not available report execution may fail! |
All available fonts are listed below the report list in the icTime => Administration : Tab Custom Reports
If the font is shown in the list and is not usable, than you are missing the logical to physical font mapping. Consider to use a a font manager library on system level (e.g. libfontconfig). If you want to manual add the font to manually to the JVM / JRE provided by Jira / Atlassian, consider the documentation provided from Oracle : https://docs.oracle.com/javase/8/docs/technotes/guides/intl/fontconfig.html The fonts listed show ONLY fonts available on your system. Please do not forget to register the 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:
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 considered for Custom Reports.
Permission | Description | Remarks |
---|---|---|
Custom Reports |
| |
Custom Reports - Execute |
| Starting from 5.8.2.6 |
Please find details for administrating permissions here.
icTime Version | Jasper Report Version | Remarks | |
---|---|---|---|
5.8.2.x - | 6.5.0 | we recommend to keep the jrxml file compatible to Jasper Report Version 6.3.0 |
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.