Configuration

Application Properties

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

jmix.reports.client.background-report-processing-timeout-ms

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

Default value: 10000.

jmix.reports.client.enable-tab-symbol-in-data-set-editor

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.use-background-report-processing

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.curl-path

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.display-device-available

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

Default value: false

jmix.reports.doc-formatter-timeout

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.formulas-post-processing-evaluation-enabled

Controls whether formulas in XLSX reports are re-evaluated after the report document is formed.

When enabled (true), LibreOffice or other spreadsheet software will recalculate all formulas in the XLSX report, ensuring the most up-to-date values are displayed. This is particularly useful when formulas in the report aren’t automatically calculated upon opening in certain spreadsheet applications.

The default value is false.

jmix.reports.history-cleanup-max-days

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.history-cleanup-max-items-per-report

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.history-recording-enabled

Activates the report execution history mechanism.

Default value: false.

jmix.reports.office-path

Sets the path to LibreOffice.

Default value: /

jmix.reports.office-ports

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

For example: jmix.reports.office-ports = 8100|8101|8102|8103|8104|8105.

Default value: 8100, 8101, 8102, 8103.

jmix.reports.pdf-fonts-directory

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

For example: jmix.reports.pdf-fonts-directory = C:/Windows/Fonts.

jmix.reports.put-empty-row-if-no-data-selected

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

Default value: true

jmix.reports.save-output-documents-to-history

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

Default value: false.

jmix.reports.use-office-for-document-conversion

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.office-path = 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.office-path application property, set it the path to LibreOffice:

    jmix.reports.office-path = /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.display-device-available application property:

    jmix.reports.display-device-available = 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.office-path application property, specify the path to LibreOffice.app, for example:

    jmix.reports.office-path = /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.