Exporting PDF Reports

The report functionality allows users to export individual views of a workbook, the content of an individual worksheet and, if available, reports prepared for the workbook as a PDF report. These reports are paginated reports, which means that they ideally fit on one or, especially in the case of tables, several printed pages. The layout of a report page, such as the page format, header and footer, etc., is defined using report layouts.

Cadenza uses WebDriver technology to generate the reports. WebDriver technology is a W3C standard that enables the programmatic remote control of a web browser. In Cadenza, the component responsible for report generation is called the report generator.

Requirements

WorkbookReport plugin activated
workbookreport settings adjusted
When installing using the ZIP file, a headless Chromium is included. Alternatively, a Selenium Grid can be used as a remote WebDriver application. This must use the stable Chromium version that Cadenza expects. For Cadenza being operated in a container, the required version can always be retrieved from its image metadata:
```
docker inspect \
  --format '{{index .Config.Labels "net.disy.cadenza.webdriver-chrome-version"}}' \
  <image-repository>:<image-tag>
```

To display layers from a geodata service in PDF reports, the report generator must have access to the geodata service. Hint for WMS/WMTS layers: If the report generator does not have access to the geodata service, access via the Cadenza server can be enforced in the Management Center for WMS/WMTS data sources.

The proxy settings made in the core configuration are also used for PDF Report creation. The settings are passed as arguments to the local or remote report generator.

The following restrictions apply:

When the proxy is explicitly defined, the username and password are not passed to the report generator because it does not support these arguments.
When configured as to use of system defaults, the properties http.proxyHost, http.proxyPort and http.nonProxyHosts are evaluated and passed to the report generator as argument.

Adjusting the Configuration

To export PDF reports, the workbookreport settings must be configured according to the following example:

With Local Report Generator

XML
YAML

workbookreport-config.xml configuration file

<workbookReportConfiguration>
  <localWebDriver>
    <webDriverExecutable>$SYSTEM{CADENZA_CHROMEDRIVER_EXECUTABLE}</webDriverExecutable>
    <webDriverBrowserExecutable>$SYSTEM{CADENZA_CHROME_EXECUTABLE}</webDriverBrowserExecutable>
    <webDriverPort>12345</webDriverPort>
  </localWebDriver>
  <webDriverWaitTimeout>PT5M</webDriverWaitTimeout>
  <threadCount>1</threadCount>
  <cadenzaUrl>http://localhost:8000/cadenza</cadenzaUrl>
</workbookReportConfiguration>

myConfig.yaml

cadenzaconfig:
  ...
  workbookreport:
    localWebDriver:
      webDriverExecutable: $SYSTEM{CADENZA_CHROMEDRIVER_EXECUTABLE}
      webDriverBrowserExecutable: $SYSTEM{CADENZA_CHROME_EXECUTABLE}
      webDriverPort: 12345
    webDriverWaitTimeout: PT5M
    threadCount: 1
    cadenzaUrl: http://localhost:8000/cadenza
  ...

Be sure to make the executables actually executable, i.e. on Linux chmod +x.

With Remote Report Generator

XML
YAML

workbookreport-config.xml configuration file

<workbookReportConfiguration>
  <remoteWebDriverUrl>http://localhost:4444</remoteWebDriverUrl>
  <webDriverWaitTimeout>PT5M</webDriverWaitTimeout>
  <threadCount>1</threadCount>
  <cadenzaUrl>http://localhost:8000/cadenza</cadenzaUrl>
</workbookReportConfiguration>

myConfig.yaml

cadenzaconfig:
  ...
  workbookreport:
    remoteWebDriverUrl: http://localhost:4444
    webDriverWaitTimeout: PT5M
    threadCount: 1
    cadenzaUrl: http://localhost:8000/cadenza
  ...

About the Report Generation Process

The user first initiates the creation of his report from the Cadenza client. The Cadenza server then prompts the configured report generator to show the report pages and export them as a PDF. The report pages themselves are created by another Cadenza instance to which the user is automatically logged in. The report is finally made available to the user as a PDF document on the Cadenza client.

Even if this architecture is distributed, the Cadenza instance(s) and the report generator can also run on the same computer.

Optimizing for Large Reports

For the generation of large reports Chromium needs a lot of memory. However, Chromium limits the amount of memory that one browser tab can use to 4 GB. So to maximize the possible report size, a bit more than 4 GB per report-generating thread should be available to Chromium.

Local Report Generator

If the report generator for a Cadenza node is co-located on the same machine - physical or virtual - ensure that the machine has sufficient memory available.

Selenium Chromium Container

If a Selenium container is used (with Kubernetes or plain Docker), that container must have enough memory assigned.

The size of the /dev/shm directory provided to the container does not matter. Cadenza disables the use of /dev/shm by sending the parameter --disable-dev-shm-usage to Chromium so that, instead of /dev/shm, the temp directory is used for storing transient data during report creation.

Optimizing for Throughput

Simply ensuring that enough memory is available (see above) is not enough to generate many reports in parallel. Additionally the number of threads dedicated to report generation has be increased.

Local Report Generator

Increasing the threadCount in workbookreport is enough.

Selenium Chromium Container

When using a Selenium Chromium Container you have to make sure that the container does not become the bottleneck. By default, the container processes only one request at a time. It is recommended to increase this limit to match the number of Cadenza nodes that use it, multiplied by the <threadCount> configured on those nodes.

The maximum number of concurrent sessions in the container can be set with the environment variable SE_NODE_MAX_SESSIONS. The actual number of concurrent sessions cannot exceed the number of CPUs assigned to the container (unless SE_NODE_OVERRIDE_MAX_SESSIONS is set to "true", which is not recommended).