Configuration

Application Properties

This section describes the application properties related to the Reports add-on in alphabetical order.

jmix.reports.client.backgroundReportProcessingTimeoutMs

Defines the processing timeout in milliseconds for the report execution if the jmix.reports.client.useBackgroundReportProcessing is set to true.

Default value: 10000.

jmix.reports.client.enableTabSymbolInDataSetEditor

Defines whether TAB key should be handled as \t symbol instead of focus navigation in Script fields of the report detail view.

Default value: false

jmix.reports.client.useBackgroundReportProcessing

Allows you to set the report execution as a background task. This property is used in order to add the cancel option.

Default value: false.

jmix.reports.curlPath

The Reports add-on uses the cURL tool to run external reports. The property value represents the path to the cURL tool.

Default value: curl.

jmix.reports.displayDeviceAvailable

false value allows running LibreOffice in the server operating system without a window interface.

Default value: false

jmix.reports.docFormatterTimeout

Sets the LibreOffice timeout in seconds for converting DOCX/XLSX to HTML/PDF.

When the time is up, the user will receive an error message.

Default value: 20

jmix.reports.historyCleanupMaxDays

The scheduled task deletes all execution history records older than the specified number of days. If the property value is 0, the scheduled task does not consider this property when deleting records.

See Cleanup the History for details on setting up the scheduled task.

Default value: 730

jmix.reports.historyCleanupMaxItemsPerReport

The scheduled task leaves no more than this number of execution history entries for every report. It is not recommended to use a number greater than 1000 as the value of this property. If the property value is 0, the scheduled task does not consider this property when deleting records. It is useful for frequently run reports such as email templates, invoicing document templates, etc.

See Cleanup the History for details on setting up the scheduled task.

Default value: 1000.

jmix.reports.historyRecordingEnabled

Activates the report execution history mechanism.

Default value: false.

jmix.reports.officePath

Sets the path to LibreOffice.

Default value: /

jmix.reports.officePorts

Specifies the comma- or vertical bar-separated list of available ports for LibreOffice.

For example: jmix.reports.officePorts = 8100|8101|8102|8103|8104|8105.

Default value: 8100, 8101, 8102, 8103.

jmix.reports.pdfFontsDirectory

Sets to the fonts directory for converting reports from HTML to PDF.

For example: jmix.reports.pdfFontsDirectory = C:/Windows/Fonts.

jmix.reports.putEmptyRowIfNoDataSelected

Sets the mode when the bands which datasets have returned no records are still displayed once.

Default value: true

jmix.reports.saveOutputDocumentsToHistory

If set to true, report results files are saved to the file store, if the jmix.reports.historyRecordingEnabled property is on. See Output documents for details.

Default value: false.

jmix.reports.useOfficeForDocumentConversion

Turns on using LibreOffice to convert the report having DOCX template to HTML/PDF, which significantly increases the conversion accuracy.

Default value: false

Installing and Configuring LibreOffice

The Reports add-on uses the LibreOffice package to output reports in PDF and DOC formats. Below we provide instructions about how to install and configure it in the application server:

For Microsoft Windows

jmix.reports.officePath = C:/Program Files (x86)/LibreOffice 5/program

On Ubuntu Server

  • Install the libreoffice package, for example, by running the following command:

    $ sudo apt-get install libreoffice

  • Configure jmix.reports.officePath application property, set it the path to LibreOffice:

    jmix.reports.officePath = /usr/lib/libreoffice/program

  • If the server does not have window interface installed, LibreOffice will start with the error, Caused by: java.awt.HeadlessException: No X11 DISPLAY variable was set, but this program performed an operation which requires it, or will simply terminate without error messages. To resolve this issue, set the jmix.reports.displayDeviceAvailable application property:

    jmix.reports.displayDeviceAvailable = false

  • You can run the following command to diagnose errors when starting LibreOffice:

    $ strace -e trace=signal /usr/lib/libreoffice/programs/office.bin --headless --accept="socket,host=localhost,port=8100;urp" --nologo --nolockcheck

For Ubuntu users who installed tomcat using apt, it is necessary to copy ~/.config/libreoffice to $CATALINA_HOME. For tomcat10, it is /usr/share/tomcat10.

After that, you should change the owner of this folder:

sudo mkdir /usr/share/tomcat10/.config
sudo cp -pr ~/.config/libreoffice /usr/share/tomcat10/.config/
sudo chown -R tomcat10.tomcat10 /usr/share/tomcat10/.config/

For macOS

  • Download the application at www.libreoffice.org.

  • Install the application.

  • In the jmix.reports.officePath application property, specify the path to LibreOffice.app, for example:

    jmix.reports.officePath = /Applications/LibreOffice.app/Contents/MacOS

LibreOffice Formulas Recalculation On Load

The LibreOffice Calc setting, found under Tools > Options > LibreOffice Calc > Formula > Recalculation on File Load, controls how LibreOffice handles formula recalculation when opening a spreadsheet file (like an XLSX report).

By default, LibreOffice might choose to not automatically recalculate formulas upon opening a file to improve load times, especially for large and complex spreadsheets. This can lead to situations where formulas display outdated results until the user manually triggers a recalculation (for example, by pressing F9 or editing a cell).

Setting Recalculation on File Load to Always recalculate forces LibreOffice to recalculate all formulas every time the file is opened. This guarantees that the displayed values are always up-to-date but may increase the file’s opening time, especially for large or computationally intensive spreadsheets. Therefore, this setting represents a trade-off between speed of opening and data accuracy. While it solves the problem of outdated formula results in most cases, it’s worth considering the performance implications for very large files.