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
: Iftrue
, one report will be compiled and a list of feature IDs will be passed in the report params. Iffalse
, one report will be compiled for each feature ID, and the result will be a multi-page report (one report per feature). Default isfalse
.format
: The report format, one ofpdf
,html
,csv
,docx
,ods
,odt
,pptx
,rtf
,xslsx
,xml
. Default ispdf
.
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 formSELECT <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
andFEATURE_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 theREADME
.
- 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
-
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 involumes/reports/fonts
respecting the naming convention described in theREADME
. -
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 ofMyReport.jrxml
belowvolumes/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 theresources
block of thedocument
configuration section intenantConfig.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 correspondingdocument_templates
resources, complementing any manually defined resources. -
To restrict document templates to specified roles, create
Document template
resources and permissions as desired. These permissions will also apply to any reports included as subreports by a parent report. -
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>
Debugging¶
- Check the logs of the
qwc-document-service
(in particular withFLASK_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