Reports¶

QWC, complemented with the qwc-document-service, provides the possibility to generate reports for features of layers whose datasource is a PostgreSQL table, based on Jasper report templates.

Setting up the document-service¶

As a first step, set up a qwc-document-service, placing your report templates below the report_dir. Read the qwc-document-service README for more information on setting up the service and to understand how to prepare and configure your report templates.

When using qwc-docker, you can configure the container as follows:

  qwc-document-service:
    image: docker.io/sourcepole/qwc-document-service:<tag>
    environment:
      <<: *qwc-service-variables
      SERVICE_MOUNTPOINT: '/api/v1/document'
      # FLASK_DEBUG: 1
    volumes:
      - ./pg_service.conf:/srv/pg_service.conf:ro
      - ./volumes/reports:/reports
      - ./volumes/reports/fonts:/srv/qwc_service/fonts
      - ./volumes/config:/srv/qwc_service/config:ro

In addition, to ensure that the qwc-config-generator automatically picks up existing reports when generating the document service configuration, ensure that the reports directory is also mounted in its container:

  qwc-config-service:
    image: docker.io/sourcepole/qwc-config-generator:<tag>
    ...
    volumes:
      ...
      - ./volumes/reports:/reports

Configuring the web client¶

As a second step, associate the report templates to theme layers to expose the reports in the web client. This is done providing a featureReport entry in a theme item in themesConfig.json as follows:

    "featureReport": {
      "<layer_name1>": "<template_name>",
      "<layer_name2>": [
        {
          "title": "<title>",
          "template": "<template_name>",
          "single_report": <false|true>,
          "format": "<pdf|docx|...>"
        },
        ...
      ],
      ...
    }

The first case example displays the shorthand syntax for assigning one report template to one layer. The second example displays the syntax for assigning one or more templates to one layer, supporting the following extra options:

• single_report: If true, one report will be compiled and a list of feature IDs will be passed in the report params. If false, one report will be compiled for each feature ID, and the result will be a multi-page report (one report per feature). Default is false.
• format: The report format, one of pdf, html, csv, docx, ods, odt, pptx, rtf, xlsx, xml. Default is pdf.

The web client will then display a link to download the report(s) for one or more selected features in the identify results dialog.

In addition, the Reports plugin provides a convenient interface to directly select a desired report layer and download the reports for one or more, or all, features of the selected layer.

Example¶

Here is an example to configure a report for a layer, whose datasource is a PostgreSQL table, assuming a qwc-docker setup.

• Create a Jasper report template using Jasper Studio with the desired layout.

  • To include data from the PostgreSQL datasource in your report, add a Postgres Data Adapter, using the name of the PG service definition in your pg_service.conf as the name of the data adapter.
  • Create a report parameter, though which the document-service will pass the primary key of report feature.

  • Define the data query in the Dataset and Query Dialog, in the form

    SELECT <fields> FROM <table_name> WHERE <pk_column> = $P{<FEATURE_PARAM_NAME>}
    

    If you need a more complex query, you'll need to explicitly specify the table_name, pk_column and FEATURE_PARAM_NAME in the document template resource configuration, see below.

  • If you want to include external resources (images, etc), set the resource path relative to the $P{REPORT_DIR} path as described in the README.

• Save your report to the document service report dir, i.e. as volumes/reports/MyReport.jrxml.

  • If you included any custom fonts in your report, place these in ttf format in volumes/reports/fonts.

  • If your report requires third party java classes, you can mount the corresponding JARs as volumes to /srv/qwc_service/libs/.

• Associate the report with a layer via themesConfig.json by adding the following to the desired theme configuration entry:

    "featureReport": {
      "my_layer": "MyReport"
    }

• Note: MyReport here denotes the relative path of MyReport.jrxml below volumes/reports, without the .jrxml extension.

• If the name of the data adapter does not match the name of a PG service definition, or if your report contains a complex data query SQL, from which the dataset table name, primary key column of feature parameter name cannot be trivially parsed, then you need to explicitly define these document_templates in the resources block of the document configuration section in tenantConfig.json, for instance:

    {
      "name": "document",
      "config": {...},
      "resources": {
        "document_templates": [
          {
            "template": "MyReport",
            "datasource": "<pg_service_name>",
            "table": "<table_name>",
            "primary_key": "<primary_key_column_name>",
            "parameter_name": "<report_parameter_name>"
          }
        ]
      }
    }

• Generate the document service configuration by running the ConfigGenerator. It will automatically pick up all *.jrxml files and generate corresponding document_templates resources, complementing any manually defined resources.

• Test your report, either through the QWC interface, or via a direct call to the document service, i.e.:

  http://localhost:8088/api/v1/document/MyReport.pdf?feature=<fid>
  

Permissions¶

Report permissions are managed through the Document template resources and permissions. They are allowed by default if permissions_default_allow is true in the tenantConfig.json.

Permissions / restrictions will by default also be applied to any reports included as subreports by a parent report. If you set permit_subreports to true in the document service config in tenantConfig.json, subreports will always be permitted if the parent report is permitted.

Debugging¶

• Check the logs of the qwc-document-service (in particular with FLASK_DEBUG: 1) to get detailed information about the report generation.
• Enable additional Java logging by mounting a logging.properties of the form

# Keep global logs at WARNING level to reduce noise
.level=WARNING

# Enable detailed logging only for JasperReports
net.sf.jasperreports.level=ALL
handlers=java.util.logging.ConsoleHandler

# Configure ConsoleHandler
java.util.logging.ConsoleHandler.level=ALL
java.util.logging.ConsoleHandler.formatter=java.util.logging.SimpleFormatter

to /srv/qwc_service/libs/logging.properties, i.e.:

    ./volumes/logging.properties:/srv/qwc_service/libs/logging.properties:ro