Have any questions?
+44 1234 567 890
Chapter 4. Configuration
4. Configuration
ReportServer is now up and running. In the following section we describe configuration options affecting the operation of ReportServer. The present document should be considered as a reference containing a brief description of the various configuration options. Keep in mind that the settings described here affect all areas of ReportServer which to describe is beyond the scope of this config guide. See the administrator's and user's guide for further information to the various areas of ReportServer. Sample configurations can be found in Appendix A.
All configuration files described in this section can be found in ReportServer's internal filesystem. You can access the internal filesystem using the administration module (administration/ file system) or using the terminal: you can open the terminal by pressing CTRL+ALT+T.
Default configuration files are created on first run of ReportServer. Later, when upgrading ReportServer to a newer version, it is probable that newly added configuration files will be missing (i.e. all configuration files added between the version originally installed and the version upgraded to). You can use the ''diffconfigfiles'' command for getting help on this, check the Administration Guide for details. Note that default values are used for configuration files that are not found.
By using the command editTextFile you can edit files directly from the terminal. You can also create new files using the command createTextFile. For further information on the workings of the terminal see the administrator's guide. Using the graphical user interface, you can select files similar to selecting files when working in the Explorer in your operating system. To do this, go to administration/file system. To edit a file, choose the tab Edit file. Note that the edit file tab is only available for text files and if a proper mime-type is specified.
Please note, that after changing a config file you need to run the terminal command config reload for the change to take effect.
Configuration files in ReportServer are usually defined in an XML format.
4.1. Datasources
In this section we will cover:
- how to define the default datasource,
- how to define datasource bundles (only available in ReportServer Enterprise),
- how to configure the connection pool,
- how to configure the internal db
4.1.1. Defining the Default Datasource
ReportServer allows to configure a single default datasource. The default datasource can then be accessed with only a single mouse click when working with reports and parameters. The default datasource is set in the file /fileserver/etc/datasources/datasources.cf.
You can use the key of the datasource or use the ID of the datasource for the assignment. Use one of the two variants for the configuration:
<defaultDatasourceKey>MY_DATASOURCE<defaultDatasourceKey>
<defaultDatasourceId>12</defaultDatasourceId>Remark. Keep in mind that the datasource key is case sensitive.
4.1.2. Configuring the Connection Pool
By default, ReportServer will pool connections to relational database systems. This increases the stability of the system, since you can define an upper limit of simultaneously open connections and, furthermore, it improves the performance at the same time since database connections are kept open and ready for use.
The connection pools can be configured both globally and per datasource. The configuration is done in the file /fileserver/etc/datasources/pool.cf.
To not use connection pools, change the attribute "disable" to "true": <pool disable="false">.
ReportServer uses the library C3P0 (http://www.mchange.com/projects/c3p0/) to perform connection pooling. To globally set a property, set the property within the <defaultconfig> tags. For data-source-specific settings, use the tag <pool16>, where 16 is the ID of the data source.
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<pool>
<defaultconfig>
<maxPoolSize>40</maxPoolSize>
<initialPoolSize>10</initialPoolSize>
<acquireRetryAttempts>10</acquireRetryAttempts>
<acquireRetryDelay>500</acquireRetryDelay>
<checkoutTimeout>60000</checkoutTimeout>
<maxConnectionAge>7200</maxConnectionAge>
<maxIdleTime>3600</maxIdleTime>
</defaultconfig>
<pool16>
<acquireRetryAttempts>20</acquireRetryAttempts>
</pool16>
</pool>
</configuration>The possible configuration settings of C3P0 can be found at http://www.mchange.com/projects/c3p0/#configuration_properties. ReportServer simply passes on any set property to C3P0.
Note that as of ReportServer 4.0.0, the current state of the connections (including total max pool size, busy connections and number of connections) is visualized in the "Connection Pool" System Console.
4.1.3. Internal database
ReportServer uses a database to buffer data coming from non-database datasources such as, for example, CSV datasources. This buffer database is called the internal database. Per default ReportServer uses the its own database for this and creates tables with the prefix rs_tmptbl_. You can change the database to be used as well as configure certain aspects of the internal database via the configuration file datasources/internaldb.cf. The default configuration file is
<configuration>
<internaldb>
<droponstartup>true</droponstartup>
<datasource>REPORTSERVER_DATASOURCE</datasource>
</internaldb>
</configuration>The droponstartup tells ReportServer to remove any temporary tables on startup. This should only be turned off for debugging purposes as having old temporary tables still available after startup will cause errors when using the internal DB. Via the datasource tag you can define the datasource (via its key) to be used as the internal database.
4.1.4. SQL limits and parameter options
The datasource parameter (a parameter that can be used to allow the user to select values from a predefined set) can return a single value or a list of values. If a user selects multiple values (or uses many filters in a dynamic list) this might lead to problems with certain database systems. This is due to the fact that the number of values that can be used in IN clauses is limited for most database systems.
You can specify the maximum number of values that are to be used in an IN clause in the file /fileserver/etc/datasources/sql.cf. ReportServer will then distribute the selected values over multiple IN-clauses.
For this set the following parameter
<incondition>
<maxsize>1000</maxsize>
</incondition>in accordance with the prerequisites of the used database system.
4.1.5. The datasource parameter
Queries that run for a long time have an impact on the performance of ReportServer. You can specify how long ReportServer should wait for the results of a parameter query. A parameter query is executed when a report is opened.
You can specify a timeout for long running parameter queries in the configuration file /fileserver/etc/datasources/parameter.cf.
Set the parameter <querytimeout>60</querytimeout> to stop queries after 60 seconds.
If you want to use the "post-processing" feature of the datasource parameter enable it using the following lines:
<postprocessing>
<enable>true</enable>
</postprocessing>In general it is good practice to have parameter queries optimized such that they run very fast such as to provide a good user experience.
The post-processing feature, for example, allows to switch parameter values or perform complex string operations. Learn more about datasource parameter post-processing in the parameter chapter in the administrator's guide.
4.2. Datasinks
Datasinks can be enabled/disabled in the /fileserver/etc/datasinks/datasinks.cf file. Here you have an entry similar as the following for each supported datasink type:
<configuration>
<sftp disabled="false" supportsScheduling="true" />
<ftp disabled="false" supportsScheduling="true" />
</configuration>he disabled option controls if the datasink is overall enabled or disabled. Further, scheduling via datasinks can be enabled or disabled via the supportsScheduling setting. Note that you can not enable scheduling if the datasink is overall disabled.
Further, you can select a default datasink per type as shown below for email / SMTP datasinks:
<email disabled="false" supportsScheduling="true">
<defaultDatasinkKey>DEFAULT_EMAIL_DATASINK</defaultDatasinkKey>
</email>Here, your default datasink is the datasink with the key DEFAULT_EMAIL_DATASINK. You can select the default datasink by key:
<email disabled="false" supportsScheduling="true">
<defaultDatasinkKey>DEFAULT_EMAIL_DATASINK</defaultDatasinkKey>
</email>or by id:
<email disabled="false" supportsScheduling="true">
<defaultDatasinkId>14</defaultDatasinkId>
</email>4.2.1. SFTP, FTPS, FTP and SCP Datasinks
Datasinks are supported as of ReportServer 3.4.0. The legacy FTP configuration in /fileserver/etc/exportfilemd/storage.cf is ignored as of version 3.4.0.
For the SFTP/FTPS/SCP datasinks to work, you have to add your SFTP/FTPS/SCP host to your .ssh/known_hosts file (https://en.wikibooks.org/wiki/OpenSSH/Client_Configuration_Files#~/.ssh/known_hosts) in order to verify the identity of the remote host, thus protecting against impersonation or man-in-the-middle attacks. Its location be configured in the /fileserver/etc/security/misc.cf file as follows.
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<knownHosts>/path/to/your/machine/.ssh/known_hosts</knownHosts>
</configuration>For manually adding a public key to the .ssh/known_hosts file, check here: https://en.wikibooks.org/wiki/OpenSSH/Client_Configuration_Files#Manually_Adding_Public_Keys_to_~/.ssh/known_hosts.
4.2.2. Email SMTP Datasinks
As of ReportServer 3.7.0, the old mail/mail.cf configuration file is deprecated. Instead, Email SMTP datasinks should be used together with a default email datasink, which can be defined in the /etc/datasinks/datasinks.cf configuration file as follows.
<email disabled="false" supportsScheduling="true">
<defaultDatasinkName>Default Email Datasink</defaultDatasinkName>
<!-- or access via ID -->
<!-- <defaultDatasinkId>14</defaultDatasinkId> -->
</email>You can use the name of the datasink, or use the ID of the datasink, for the assignment. Use one of the two variants above for the configuration.
Note that you can configure a default datasink per datasink type, so this is not limited to email SMTP datasinks.
4.3. Dynamic Lists
In Dynamic Lists, users can use Computed Columns. Computed columns allow users to extend the list of columns by fields which do not exist in the source but which can be constructed from existing fields. Computed Columns are based on SQL.
In /fileserver/etc/dynamiclists/computedcolumn.cf you can specify which SQL functions can be used with Computed Columns.
Add those functions that may be used by your users.
Example:
<function>abs</function>
Note that SQL functions vary depending on the database system.
We strongly recommend against allowing to use functions that can change data. Further, the database user used for report execution should not have write access.
4.3.1. Theming
In ReportServer Enterprise Edition you can change how the PDF and HTML output of a dynamic list is outlined. Further information on this can be found in the Administration Guide.
4.4. Setting up the Scheduler
With ReportServer you can schedule reports and distribute the result either using mail, directly into a TeamSpace, or sent to any datasink configured, (check Section 4.2. for more details). The next section discusses some important settings.
4.4.1. Mail Server Configuration
Note that the old /fileserver/etc/mail/mail.cf configuration file is deprecated. Please use email SMTP datasinks instead together with the default email datasink configuration.
In order for ReportServer to be able to send mails you must specify the mail server settings. Make the following configurations in your Email SMTP datasink.
Setting up the SMTP server. Replace the values host, port, username, and password according to your SMTP server.
Host: mail.yourmailserver.com
Port: 25
Username: rs@yourmailserver.com
Password: passwordsecret
SSL: false
TLS enable: false
TLS require: falseIf you are using SSL or TLS please also specify these values. Next, configure the sender name, email address and forceSender options. If the forceSender option is set to true, the emails will be sent using the given (generic) sender details. If set to false, the specific user sending the email will determine the sender details.
Sender: rs@yourmailserver.com
Sender name: ReportServer
Force sender: false
Encryption policy: allow_mixedThe encryption policy option controls whether or not mails have to be encrypted or whether it is ok to send mails unencrypted if a user's public key is not specified. Choose between strict and allow_mixed. Note that if you choose strict then mails to users that do not have public key registered with ReportServer will not receive any messages.
Details on setting the default email datasink can be found in Section 4.2.2.
4.4.2. Scheduler settings
ReportServer comes with a powerful scheduler. ReportServer's scheduler allows you to schedule the execution of reports. The executed report can then either be emailed, stored in a folder in a TeamSpace, or sent to any datasource configured. Refer to Section 4.2. Datasinks for more details.
The schedule and report recipients are user provided on scheduling. You can configure the messages that ReportServer will send out on certain events. Each message can be customized to your specifications.
ReportServer will send out the following emails:
- email with attached completed report (mailaction) (deprecated, use fileactionEmailDatasink instead),
- email if a report has been placed into a TeamSpace (fileaction),
- email if a report has been sent to an email SMTP server (fileactionEmailDatasink),
- email if a report has been sent to a table datasink (fileactionTableDatasink),
- email if a report has been sent to a SFTP server (fileactionSftp),
- email if a report has been sent to a FTPS server (fileactionSftp),
- email if a report has been sent to a FTP server (fileactionFtp),
- email if a report has been sent to a Samba - SMB/CIFS server (fileactionSamba),
- email if a report has been sent to a SCP (SSH) server (fileactionScp),
- email if a report has been sent to the local filesystem (fileactionLocalFilesystem),
- email if a report has been sent to a Dropbox datasink (fileactionDropbox),
- email if a report has been sent to a Google Drive datasink (fileactionGoogleDrive),
- email if a report has been sent to an Amazon S3 datasink (fileactionAmazonS3),
- email if a report has been sent to a Box datasink (fileactionBox),
- email if a report has been sent to a Printer datasink (fileactionPrinter),
- email if a report has been sent to a Script datasink (fileactionScriptDatasink),
- email on schedule (notification - scheduled),
- email if a schedule job is revoked (notification - unscheduled),
- email if a scheduled job failed (notification - failed)
The following configurations are done in the file /fileserver/etc/scheduler/scheduler.cf. To include information such as "the user who created the schedule entry", "the report's name" etc. in your message you can use a variety of expressions. Substitutions are defined in the ReportServer formula language. You will find further information about the ReportServer formula language in the Administrator's, as well as in the User Guide.
4.4.3. Available Substitutions
| Expression | Description |
| ${job.getName()} | job's name |
| ${job.getDescription()} | job's description |
| ${job.getId()} | job's ID |
| ${report.getName()} | report's name |
| ${report.getDescription()} | report's description |
| ${report.report.getKey()} | report's key |
| ${report.getId()} | report's ID |
| ${user.getUsername()} | username |
| ${user.getFirstname()} | first name of user |
| ${user.getLastname()} | last name of user |
| ${user.getEmail()} | user's email address |
| ${user.getTitle()} | user's title |
| ${user.getId()} | id of user |
| ${executor} | job's executor. You can use the same methods above as with user |
| ${scheduledBy} | job's scheduler. You can use the same methods above as with user |
| ${teamspace.getName()} | name of TeamSpace (only available in fileaction) |
| ${folder.getName()} | name of folder in TeamSpace (only available in fileaction) |
| ${folder} | name of folder in FTP server (only available in fileactionFtp) |
| ${message} | the message that was specified by the user on scheduling |
| ${subject} | the subject that was specified by the user on scheduling |
| ${recipients} | A list of the job recipients. Please check below for the exact configuration (list of users) |
| ${owners} | A list of the job owners. Please check below for the exact configuration (list of users) |
| ${filename} | filename as specified by the user (report is scheduled in teamspace) |
| ${nextDates} | date of next execution |
| ${RS_CURRENT_DATE} | current date |
| ${errMsg} | error message on erroneous execution |
| ${stacktrace} | detailed stacktrace on failed execution |
List of users
For substitution of a list of users (currently supported: list of job recipients and list of job owners), you can use a fluent API that allows you to configure the output exactly as you need. Available methods for this are:
| ${withSeparator()} | use a given separator between users. Default is a new line. |
| ${addString('','')} | add a String, e.g. a comma |
| ${addBlankspace()} | add a blank space |
| ${addNewline()} | add a new line |
| ${addUsernames()} | add usernames |
| ${addFirstnames()} | add first names |
| ${addLastnames()} | add last names |
| ${addEmails()} | add emails |
| ${addTitles()} | add titles |
| ${addIds()} | user ids |
| ${print()} | create the result string. This method has to be called in the last place. |
As mentioned, you can use a fluent API for configuring the output. E.g.,
${recipients
.addFirstnames()
.addBlankspace()
.addLastnames()
.addBlankspace()
.addString("(")
.addUsernames()
.addString(")")
.print()
}will print the following:
Barry Jones (bjones)
Diane Murphy (dmurphy)
Gerard Hernandez (ghernande)
Larry Bott (lbott)
If you want to separate the users by a comma instead of a new line, you can enter use the withSeparator() method as follows:
${recipients
.withSeparator(", ")
.addFirstnames()
.addBlankspace()
.addLastnames()
.addBlankspace()
.addString("(")
.addUsernames()
.addString(")")
.print()
}which will print the following data:
Barry Jones (bjones), Diane Murphy (dmurphy), Gerard Hernandez (ghernande), Larry Bott (lbott)
Below you can find some example configurations:
Configuration of email message with attached report (successful execution)
<mailaction html="false">
<subject>${subject}</subject>
<text>Text of message: ${message}</text>
<attachment>
<name>rep-${report.getName()}-${RS_CURRENT_DATE}</name>
</attachment>
</mailaction>Configuration on successful execution of report and storage in TeamSpace
<fileaction disabled="false" html="false">
<subject></subject>
<text></text>
</xmlcode>Configuration on successful execution of report sent to email SMTP server
<fileactionEmailDatasink disabled="false" html="false">
<subject></subject>
<text></text>
</fileactionEmailDatasink>Configuration on successful execution of report sent to table datasink
<fileactionTableDatasink disabled="false" html="false">
<subject></subject>
<text></text>
</fileactionTableDatasink>Configuration on successful execution of report and storage in SFTP server
<fileactionSftp disabled="false" html="false">
<subject></subject>
<text></text>
</fileactionSftp>Configuration on successful execution of report and storage in FTPS server
<fileactionFtps disabled="false" html="false">
<subject></subject>
<text></text>
</fileactionFtps>Configuration on successful execution of report and storage in FTP server
<fileactionFtp disabled="false" html="false">
<subject></subject>
<text></text>
</fileactionFtp>Configuration on successful execution of report and storage in Samba server
<fileactionSamba disabled="false" html="false">
<subject></subject>
<text></text>
</fileactionSamba>Configuration on successful execution of report and storage in SCP (SSH) server
<fileactionScp disabled="false" html="false">
<subject></subject>
<text></text>
</fileactionScp>Configuration on successful execution of report and storage in the local filesystem
<fileactionLocalFilesystem disabled="false" html="false">
<subject></subject>
<text></text>
</fileactionLocalFilesystem>Configuration on successful execution of report and storage in Dropbox
<fileactionDropbox disabled="false" html="false">
<subject></subject>
<text></text>
</fileactionDropbox>Configuration on successful execution of report and storage in OneDrive - SharePoint (O365)
<fileactionOneDrive disabled="false" html="false">
<subject></subject>
<text></text>
</fileactionOneDrive>Configuration on successful execution of report and storage in Google Drive
<fileactionGoogleDrive disabled="false" html="false">
<subject></subject>
<text></text>
</fileactionGoogleDrive>Configuration on successful execution of report and storage in Amazon S3 bucket
<fileactionAmazonS3 disabled="false" html="false">
<subject></subject>
<text></text>
</fileactionAmazonS3>Configuration on successful execution of report and storage in Box
<fileactionBox disabled="false" html="false">
<subject></subject>
<text></text>
</fileactionBox>Configuration on successful execution of report and storage in Printer datasinks
<fileactionPrinter disabled="false" html="false">
<subject></subject>
<text></text>
</fileactionPrinter>Configuration on successful execution of report and storage in Script datasinks
<fileactionScriptDatasink disabled="false" html="false">
<subject></subject>
<text></text>
</fileactionScriptDatasink>Configuration of notifications on scheduling, unscheduling and execution errors
<notification disabled="false" html="false">
<scheduled>
<subject></subject>
<text></text>
</scheduled>
<unscheduled>
<subject></subject>
<text></text>
</unscheduled>
<failed>
<subject></subject>
<text></text>
</failed>
</notification>If you would like to send emails in the HTML format please set the corresponding html attribute to "true".
In case you do not want to have one or more notifications, you can disable the individual notifications using the disabled attribute:
<fileaction disabled="true" html="false">If you do not want to use the scheduler you can disable it using
<properties>
<disabled>true</disabled>
</properties>You can also disable the scheduler by setting the following property in your reportserver.properties file:
rs.scheduler.disable = true
If the property is set both in reportserver.properties and in /fileserver/etc/scheduler/scheduler.cf, the property set in reportserver.properties is taken into account, while the one set in /fileserver/etc/scheduler/scheduler.cf is ignored.
Keep in mind that this changes will only take effect after reboot. To enable or disable the scheduler while ReportServer is running, use the terminal command scheduler daemon start/stop. This command only works if the scheduler is not disabled in the file reportserver.properties. If it is, you first have to delete this property in order to be able to enable/disable the scheduler while ReportServer is running. Refer to the Administration Guide for more information on this command.
Further, refer to Section 4.12. Scheduler Settings for more scheduler settings.
4.5. Remote RS Server Settings
ReportServer 4.6.0 introduced new ''Remote RS Server'' objects as explained in the Administration Guide. Also, new rpull terminal commands were introduced in order to pull/copy remote entities, e.g. reports from a remote RS installation into the local RS installation, e.g. from PROD to TEST.
In order to be able to import remote reports, their datasources must be able to be mapped to local datasources. This mapping is defined via the /etc/main/rssync.cf configuration file explained next.
The default /etc/main/rssync.cf configuration file is shown below:
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<mappings>
<datasources>
<priorities>
<priority>mapping</priority>
<priority>same-key</priority>
</priorities>
<key-mappings>
<!--
<key-mapping>
<remote>REMOTE_KEY_1</remote>
<local>LOCAL_KEY_1</local>
</key-mapping>
<key-mapping>
<remote>REMOTE_KEY_2</remote>
<local>LOCAL_KEY_2</local>
</key-mapping>
-->
</key-mappings>
</datasources>
</mappings>
</configuration>The datasource mapping is performed via datasource keys by the key-mapping elements.
For example, the following configuration maps the remote datasource with key MY_REMOTE_DATASOURCE to the local datasource with key MY_LOCAL_DATASOURCE.
<key-mapping>
<remote>MY_REMOTE_DATASOURCE</remote>
<local>MY_LOCAL_DATASOURCE</local>
</key-mapping>The priorities element defines the mapping priorities. There are currently two types of mappings:
- mapping: the explicit mapping defined by the key-mapping elements.
- same-key: implicit mapping of datasources with the same key.
For example, in the following configuration, ReportServer tries first to map the datasources via the explicit key-mapping elements. If no mapping is found, it tries to find a local datasource with the same key.
<priorities>
<priority>mapping</priority>
<priority>same-key</priority>
</priorities>On the contrary, in the following configuration, ReportServer tries first to find a local datasource with the same key. If no implicit key mapping could be found, it tries to map the datasources via the explicit key-mapping elements.
<priorities>
<priority>same-key</priority>
<priority>mapping</priority>
</priorities>4.6. Report execution error log settings
You may configure the exact detailed information your ReportServer should log in case of report execution failure. This detailed information can be set in the main/error-log.cf configuration file.
The results are printed in a JSON string for easy result analysis. Note that the order of the properties is preserved in the result's JSON string.
Per default, ReportServer logs the following information:
| error | a description of the root error causing the failure |
| report_id | the ID of the report |
| report_name | the name of the report |
| base_report_id | the ID of the base report (in case of variants) |
| base_report_name | the name of the base report (in case of variants) |
| executing_user_id | the ID of the user trying to execute the report |
| report_output_format | the output format of the report (e.g. HTML, PDF, etc) |
| report_uuid | the UUID (Universally Unique Identifier) of the report |
Available are the properties discussed below.
4.6.1. Error properties
The following properties allow you to print information of the root error.
error - a description of the root error causing the failure
4.6.2. Report properties
The following properties allow you to print information of the report which is failing.
| report_id | the ID of the report |
| report_name | the name of the report |
| report_key | the key of the report |
| report_type | the type of the report, e.g. TableReportVariant, JasperReport, etc |
| base_report_id | the ID of the base report (in case of variants) |
| base_report_name | the name of the base report (in case of variants) |
| base_report_key | the key of the base report (in case of variants) |
| base_report_type | the type of the base report (in case of variants), e.g. TableReportVariant, JasperReport, etc |
| report_output_format | the output format of the report (e.g. HTML, PDF, etc) |
| report_uuid | the UUID (Universally Unique Identifier) of the report |
4.6.3. User properties
The following properties allow you to print information of the user trying to execute the report which is failing.
| executing_user_id | the ID of the user trying to execute the report |
| executing_user_username | the username of the user trying to execute the report |
| executing_user_firstname | the first name of the user trying to execute the report |
| executing_user_lastname | the last name of the user trying to execute the report |
4.6.4. Datasource properties
The following properties allow you to print information of the failing report's datasource.
| datasource_id | the ID of the report's datasource |
| datasource_name | the name of the report's datasource |
| datasource_path | the path of the report's datasource in the fileserver file system |
| datasource_type | the type of the report's datasource, e.g. DatabaseDatasource, ScriptDatasource, etc |
In addition to the properties above, you can use the following for DatabaseDatasources (i.e. for relational databases).
| datasource_database_query | the report's datasource query. Note that the query is printed exactly as entered into the datasource's ''query'' field, i.e. no parameter replacement is shown in the output. |
| datasource_database_information | general information of the report's datasource. This information includes the following:
|
| datasource_database_jdbc_properties | the JDBC properties of the report's datasource. |
4.6.5. General properties
The following properties allow you to print general information of your ReportServer's installation. Basically, this is the same information you may find in your ''General Info'' system console.
| java_version | your exact Java version |
| java_home | environment variable pointing to the your Java installation directory |
| java_vm_arguments | the Java Virtual Machine arguments |
| application_server | your application server, e.g. ''Apache Tomcat/9.0.68'' |
| catalina_home | the root of your application server installation, for example ''/home/tomcat/apache-tomcat-9.0.10'' or ''C:/Program Files/apache-tomcat-9.0.10'' |
| catalina_home | the root of a runtime configuration of a specific application server instance |
| log_files_directory | path to the directory where the log files are located |
| rest_url | the REST access point |
| request_url | the complete request URL |
| request_scheme | the name of the scheme used to make the request, for example, ''http'', ''https'' |
| request_server_name | the host name of the server to which the request was sent |
| request_server_port | the port number to which the request was sent |
| request_context_path | the portion of the request URI that indicates the context of the request. The context path always comes first in a request URI. The path starts with a ''/'' character but does not end with a ''/'' character. For servlets in the default (root) context, this method returns ''''. |
| request_protocol | the name and version of the protocol the request uses in the form protocol/majorVersion.minorVersion, for example, ''HTTP/1.1'' |
| config_directory | path to your configured external configuration directory |
| os_version | your operation system, e.g. ''Windows Server 2022'' |
| reportserver_version | your ReportServer's complete version |
| locale | your current ReportServer's locale |
| jvm_locale | the locale of your Java Virtual Machine |
| jvm_user_language | the language of your Java Virtual Machine user, e.g. ''de'' |
| jvm_user_country | the country of your Java Virtual Machine user, e.g. ''DE'' |
| jvm_user_timezone | the timezone of your Java Virtual Machine user, e.g. ''Europe/Berlin'' |
| jvm_file_encoding | the file encoding of your Java Virtual Machine user, e.g. ''UTF-8'' |
| known_hosts_file | path to your configured known_hosts file |
| supported_ssl_protocols | the supported SSL protocols for the current SSL context |
| default_ssl_protocols | the default SSL protocols for the current SSL context |
| enabled_ssl_protocols | the enabled SSL protocols for the current SSL context |
| groovy_version | your exact Groovy version |
| static_pams | a list of your installed static PAMs (Pluggable Authentication Modules) |
4.6.6. Memory properties
The following properties allow you to print information of the current memory settings during the report's execution failure. This is basically the same information your meminfo terminal command prints.
| memory_used | your current memory usage |
| memory_free | the amount of free memory in the Java Virtual Machine |
| memory_total | the total amount of memory in the Java Virtual Machine. The value returned by this method may vary over time, depending on the host environment. |
| memory_max | the maximum amount of memory that the Java virtual machine will attempt to use. |
4.7. Export settings
Regarding the export to PDF and Microsoft Excel, there are several options that you can set. In /fileserver/etc/exportfilecmd/excelexport.cf you can specify in which format Excel documents are to be exported. You can choose between the old XLS and the current XLSX format. If you have selected the XLSX format, ReportServer allows to stream the data to the client. This means, that the chunks of resulting Excel file are sent to the user while it is still being created. Streaming result files can significantly reduce processing time.
To specify the Excel format and whether or not to use streaming, adjust the following parameters:
<format>xlsx</format>
<stream>true</stream>Further, you can specify the title of the data and configuration sheets in the resulting Excel file by the following parameters:
<datasheet>Dynamic list</datasheet>
<configsheet>Configuration</configsheet>Refer to the ''output_parameters'', ''output_filters'', and ''output_complete_configuration'' report parameters in the Admin Guide for more information on this.
You can specify document properties (title, creator and author) of PDF files in the configuration file /fileserver/etc/exportfilecmd/metadata.cf. The texts specified here will be included in newly generated PDF files.
Modify the following parameters:
<title>title</title>
<creator>ReportServer</creator>
<author>ReportServer</author>As with email notifications you can use substitutions to dynamically populate the fields. The following substitutions are available:
Available Substitutions
| Expression | Description |
| ${user.getUsername()} | username |
| ${user.getFirstname()} | user's first name |
| ${user.getLastname()} | user's last name |
| ${user.getEmail()} | user's email address |
| ${user.getTitle()} | user's title |
| ${user.getId()} | user's id |
You can further specifiy the default character set used by ReportServer. In the configuration file /fileserver/etc/main/main.cf you will find the option charset. By default, the charset UTF-8 is used.
4.8. UI Customization
In this section we cover the possibilities of customizing the user interface. ReportServer provides the following customization options:
- Specifying the default language,
- Customizing error messages,
- Customize the theme,
- customize PDF preview,
- customize the report documentation,
- add tabs based on context
Further customization options are available with the use of ReportServer scripts. More information on ReportServer scripts can be found in the Administration Guide.
4.8.1. Specifying the available languages
Any visible text in ReportServer can, in principle, be displayed in any language. The languages available on log-in can be defined in the configuration file /fileserver/etc/main/localization.cf.
<default>de</default>The "default" property specifies which language to use as default language.
<locales>en,fr,de</locales>The "locales" property specifies a comma-separated list of available languages. If the property is not specified, all supported languages are available for selection.
Remark. The user's selection is stored in a cookie. Thus, the change of the default locale will not override any locale settings done by a user previously.
Remark. A large part of the translations have been generated in a semi-automatic way and are thus far from perfect. If you are a native speaker in one of the languages and would like to contribute please contact us at info@infofabrik.de.
4.8.2. Customization of error messages
Errors can occur due to various reasons.
Typical errors are:
- an error occurs on the database during report execution, because:
- a table does not exist,
- a column does not exist,
- there is a syntax error in the underlying SQL,
- the JDBC driver was not installed
- etc.
- the connection pool does not have any free connections
An exception is thrown whenever an error occurs in ReportServer. The exception is composed of: a title, error message, and the stack trace.
In /fileserver/etc/main/templates.cf you can customize the error message that is displayed on errors that occur during the export of reports.
When customizing the error message you should give clear instructions as to what the affected employee should do in this case. Usually you would specify the contact address of an administrator or help desk. When customizing, the following substitutions are available: ${headline}, ${msg} and ${stacktrace}.
4.8.3. Customization of theming
In ReportServer Enterprise Edition it is possible to customize the theme via the /fileserver/ui/theme.cf config file. Further information on this can be found in the administration guide.
4.8.4. Preview for PDF reports
In the configuration file /fileserver/etc/ui/previews.cf you can specify how to render PDF previews. The options are ${native} (to use the native browser capabilities), ${jsviewer} (to use a javascript library) or ${image} to not render a PDF at all, but to only render the first page as an image. Also note that users can overwrite the settings within their profiles.
4.8.5. Adding contextual tabs
Using the configuration file /fileserver/etc/ui/urlview.cf you can define context aware tabs to be displayed in the TeamSpace or in the administration module (e.g., report management, user management, etc.). This allows you to, for example, display the documentation report directly whenever a user selects a report in the TeamSpace.
The configuration of extra tabs is split into two parts:
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<adminviews>
</adminviews>
<objectinfo>
</objectinfo>
</configuration>Tabs to be displayed in the administration module go into the tags and tabs for the TeamSpace are put within the tags, respectively. The default configuration does not add any additional tabs for the admin interface, but adds several tabs to the TeamSpace:
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<adminviews>
</adminviews>
<objectinfo>
<view>
<types>net.datenwerke.rs.tsreportarea.client.tsreportarea.dto.TsDiskReportReferenceDto</types>
<name>${msgs['net.datenwerke.rs.core.service.urlview.locale.UrlViewMessages']['info']}</name>
<url>rs:reportdoc://${reportId}/${id}</url>
</view>
<view>
<types>net.datenwerke.rs.tsreportarea.client.tsreportarea.dto.TsDiskReportReferenceDto</types>
<name>${msgs['net.datenwerke.rs.core.service.urlview.locale.UrlViewMessages']['history']}</name>
<url>rs:revisions://${reportId}</url>
</view>
<view>
<types>net.datenwerke.rs.tsreportarea.client.tsreportarea.dto.TsDiskReportReferenceDto</types>
<name>${msgs['net.datenwerke.rs.core.service.urlview.locale.UrlViewMessages']['preview']}</name>
<url>rs:reportpreview://${reportId}</url>
</view>
</objectinfo>
</configuration>Each <view> tag adds a new tab. The <types> tag allows to define for which types of objects the tab is displayed and <name> provides a name (in the above example, the name is localized, but you could also simply write <name>SomeName</name>. Finally, the <url> tag takes a URL that is to be displayed. In the above example we have three custom ReportServer URLs that access custom functionality, the first accesses a documentation report, the second a revisions report and the last one a preview of the report. Via the replacement ${reportId} the id of the object is added to the URL.
In the following we go through the process of adding new tabs step by step.
Adding a new Tab
To add a new tab, you define a <view> tag. For adding a tab to the TeamSpace whenever a report is selected add the following <view> tag within the <objectinfo> section.
<view>
<types>
net.datenwerke.rs.tsreportarea.client.tsreportarea.dto.TsDiskReportReferenceDto
</types>
<name>Some Additional Information</name>
<url>
reportserver/reportexport?key=someKey&format=html&p_reportId=${reportId}
</url>
</view>The above will execute the report with key "someKey" and pass the given report id as parameter. The following types are available in TeamSpaces.
All Objects in a TeamSpace:
net.datenwerke.rs.tsreportarea.client.tsreportarea.dto.AbstractTsDiskNodeDto
All folders in a TeamSpace:
net.datenwerke.rs.tsreportarea.client.tsreportarea.dto.TsDiskFolderDto
All reports and variants in a TeamSpace:
net.datenwerke.rs.tsreportarea.client.tsreportarea.dto.TsDiskReportReferenceDto
All exported reports which were, for example, created by the scheduler:
net.datenwerke.rs.scheduleasfile.client.scheduleasfile.dto.ExecutedReportFileReferenceDto
The name field defines the tab's name. The url is the address that is displayed. This also allows you to access external addresses, that are then displayed within the tab.
For the report documentation you need to use the special ReportServer URL:
rs:reportdoc://${reportId}/${id}
As you can see there are two placeholders in the above url: ${reportId} and . The following replacements are available
| id | the object's id |
| type | the object's type |
| username | the current user's username |
Note that TeamSpaces do not only contain report references. Thus, the replacement ${id} will contain the id of the reference rather than the id of the referenced report. For this, there is the special replacement called ${reportId} which is only available for report references.
Similarly, to the report documentation in the TeamSpace you can display additional information on any selected object in the administration module. In the administration module you can add tabs to objects in the report management, user management, dadget management, datasource management and fileserver modules. These are configured within the <adminviews> tag.
The following tables describe which types can be used. Note that the type must be used together with the corresponding prefix.
4.8.6. Customization of the Login Page
Following is a quick guide for those who want to completely exchange the ReportServer login page by a custom looking page. In the following we assume that the FileServer contains a folder /resources/public and that the public folder is marked as ''web accessible''. In case not, you can either mark it with the ''web accessible'' checkbox in the UI, or use the following commands:
cd /fileserver/resources
dirmod webaccess public trueAs a first step we are going to create a very simple login page, something along the following lines:
<html>
<head>
<title>Custom Login</title>
</head>
<body>
My custom login page
<form method="post" action="">
<label for="user">username:</label>
<input type="text" name="user" /> <br/>
<label for="pw">password:</label>
<input type="password" name="pw" /></br>
<input type="submit"/>
</form>
</body>
</html>The page consists of a single form with a username and password field. We store the above as login.html in the folder /resources/public. For this, for example open the terminal (CTRL+ALT+T) and go for
cd /fileserver/resources/public
createTextFile login.htmlAs the public folder is accessible for anybody (even if the user is not logged in) we can access it via the fileServerAccess servlet. That is, if your ReportServer is accessible via the url reporting.mycompany.com/ then you should see the login page if you go to http://reporting.mycompany.com/reportserver/fileServerAccess?path=/resources/public/login.html.
Now what was missing in the above login page was the intended target of the form. For this we will create a publicly accessible script that handles the form data. As scripts always go into the bin folder we create a folder public beneath the bin folder and add a script customauth.groovy.
cd /fileserver/bin
mkdir public
cd public
createTextFile customauth.groovy
dirmod webaccess public trueTo see that everything worked, we use the following simple script which simply outputs the parameter user:
def user = httpRequest.getParameter('user')
return userNote that you have access to the request and response via the httpRequest and httpResponse variables. What is left is to change the action attribute of the login.html page to point to the script, that is, we need to change it to http://reporting.mycompany.com/reportserver/scriptAccess?path=/bin/public/customauth.groovy.
<html>
<head>
<title>Custom Login</title>
</head>
<body>
My custom login page
<form method="post" action="http://reporting.mycompany.com/ReportServer/reportserver/scriptAccess?path=/bin/public/customauth.groovy">
<label for="user">username:</label>
<input type="text" name="user" /> <br/>
<label for="pw">password:</label>
<input type="password" name="pw" /></br>
<input type="submit"/>
</form>
</body>
</html>The Authentication
What we have so far is that we have a custom login page and a script which is the target. What we need is that the script can actually perform the login operation if the provided credentials match. For this we will use the AuthenticatorService located in
net.datenwerke.security.service.authenticator.AuthenticatorServiceIn the following we check for a username root and a password 123. If found we perform a login for user with id 6 (which in my case is the root user).
import net.datenwerke.security.service.authenticator.AuthenticatorService
def service = GLOBALS.getInstance(AuthenticatorService).get()
def user = httpRequest.getParameter('user')
def pw = httpRequest.getParameter('pw')
if( 'root' == user && '123' == pw ){
service.setAuthenticated(3) // the id of the root user
httpResponse.sendRedirect('http://reporting.mycompany.com/ReportServer/ReportServer.html');
return null
} else {
return 'Could not authenticate'
}If all went well you can now logoff and log in via the custom page http://reporting.mycompany.com/reportserver/fileServerAccess?path=/resources/public/login.html.
Authentication against the ReportServer User Database
In the above example we had a custom script to handle the authentication of a single user. This of course does not scale well and for any real scenario one would like to authenticate against a user database. In the following we show how to authenticate against ReportServer's own user database. For this we can again use the AuthenticatorService which offers a method authenticate that triggers the built-in authentication mechanisms.
ReportServer's built-in authentication is structured in so called pluggable authentication modules (short PAM) which perform the actual authentication. The active PAMs are configured in the reportserver.properties configuration file and usually only a single PAM is active:
rs.authenticator.pams = net.datenwerke.rs.authenticator.service.pam.UserPasswordPAMAuthoritativeThe above config loads the UserPasswordPAM module in authoritative mode (more information on the PAMs can be found in the configuration guide). This PAM expects a username and password and then sets of to authenticate against the ReportServer user database. The authoritative flag means that if the UserPasswordPAM cannot authenticate a user that it will then trigger an abort. This can become necessary when you would like to combine multiple different PAMs.
As explained, the AuthenticatorService's authenticate method triggers the internal authentication process. That is, it expects an array of so called AuthTokens (which can be basically anything) and then hands these to the registered PAMs. The PAMs are then asked in turn whether or not they can authenticate a user. For this they use the AuthToken array. The UserPasswordPAM thus expects a username and password as an AuthToken. This is encapsulated in the UserPasswordAuthToken which is located in
net.datenwerke.rs.authenticator.client.login.dto.UserPasswordAuthTokenThe authenticate method returns an AuthenticationResult which can be asked whether the authentication succeeded (isAllowed()). In the following script we combine our earlier example with an authentication against ReportServer's user database.
import net.datenwerke.security.service.authenticator.AuthenticatorService
import net.datenwerke.security.client.login.AuthToken
import net.datenwerke.rs.authenticator.client.login.dto.UserPasswordAuthToken
def service = GLOBALS.getInstance(AuthenticatorService)
def user = httpRequest.getParameter('user')
def pw = httpRequest.getParameter('pw')
/* construct authentication tokens */
def token = new UserPasswordAuthToken()
token.username = user
token.password = pw
def result = service.authenticate([token] as AuthToken[])
if(result.isAllowed()){
httpResponse.sendRedirect('http://reporting.mycompany.com/ReportServer/ReportServer.html')
return null
}
return 'Could not authenticate'Now your custom login page should be fully functional. The logout part, explained next, should be customized as well.
Custom Logout
Currently when a user logs out, the user will be taken back to the original ReportServer login page. In order to change that we need to change the config file located in etc/security/misc.cf within the ReportServer filesystem. If we add
<logout>
<url>http://reporting.mycompany.com/reportserver/fileServerAccess?path=/resources/public/login.html</url>
</logout>to the config, then on logout ReportServer will redirect the user to http://reporting.mycompany.com/reportserver/fileServerAccess?path=/resources/public/login.html.
The complete example can found here: https://github.com/infofabrik/reportserver-samples/tree/main/src/net/datenwerke/rs/samples/admin/login/simple.
Advanced example
Based on the previous examples, you can used advanced techniques, together with e.g. JQuery: https://jquery.com/ to further customize your login page. An example of this can be found here: https://github.com/infofabrik/reportserver-samples/tree/main/src/net/datenwerke/rs/samples/admin/login/advanced.
4.8.7. Objects in Report Management
| Type | Description |
| AbstractReportManagerNodeDto | All objects in the report management tree |
| ReportDto | reports |
| ReportFolderDto | folders |
4.8.8. Objects in User Management
| Type | Description |
| AbstractUserManagerNodeDto | All objects in the user management tree |
| UserDto | users |
| GroupDto | groups |
| OrganisationalUnitDto | organisational units (folders) |
4.8.9. Objects in the file server
| Type | Description |
| AbstractFileServerNodeDto | All objects in the file server |
| FileServerFolderDto | folders |
| FileServerFileDto | files |
4.8.10. Objects in Datasource Management
| Type | Description |
| AbstractDatasourceManagerNodeDto | all objects in datasource management |
| DatasourceFolderDto | folders |
| DatasourceDefinitionDto | datasources |
4.8.11. Objects in Dadget Management
| Type | Description |
| AbstractDashboardManagerNodeDto | All objects in the dashboard tree |
| DashboardNodeDto | dashboards |
| DashboardFolderDto | folders |
The following example would display a tab which displays the website at Url http://www.mycompany.com/employee.
<adminviews>
<view>
<types>net.datenwerke.security.client.usermanager.dto.UserDto</types>
<name>User Information</name>
<url>http://www.mycompany.com/employee=${id}</url>
</view>
</adminviews>4.9. Extensions
ReportServer has a modular design which is exposed in ReportServer Enterprise Edition to allow for customization. The extension points are called hooks. Extensions are written in groovy (https://groovy-lang.org/) and can hook into various places in ReportServer. In order to use scripts, you must configure certain properties in the configuration file /fileserver/etc/scripting/scripting.cf.
This file controls whether scripts are enabled to begin with. Furthermore, you have to specify a path (in the internal filesystem) beneath which scripts can be placed (this helps to allow users to create/edit files in the file system without giving them the rights to write scripts). Finally, you can name a script which is executed on ReportServer startup and one which is executed whenever a user logs in.
<scripting>
<enable>true</enable>
<restrict>
<location>bin</location>
</restrict>
<startup>
<login>fileserver/bin/onlogin.groovy</login>
<rs>fileserver/bin/onstartup.groovy</rs>
</startup>
</scripting>In the above example we allow scripts only in the bin folder (and subfolders). We defined the script fileserver/bin/onlogin.groovy as the script that is executed whenever a user logs in (note that the script is executed with the current user, that is, the user that logged in and thus the user must have the rights to execute this script). The second, on startup script is executed without any user.
The onstartup and onlogin scripts shipped with the ReportServer demo data allow you to easily execute your own scripts. The onstartup script executes all scripts in the folder /fileserver/bin/onstartup.d. Likewise, the onlogin.groovy script executes all scripts within /fileserver/bin/onlogin.d.
Further information on ReportServer scripts can be found in the administration guide and the specialized scripting guide.
4.10. Executing Reports using URLs
You can configure ReportServer to allow other applications to call reports or to include reports into external websites. For this ReportServer allows to call and configure reports directly using a specific URL. You can find more information about how reports can be accessed using a URL in the administrators guide.
The old httpauthexec functionality was replaced in ReportServer 3.0. See the Administration Guide for further information on how to make reports available via the URL without login.
4.11. Misc Settings
ReportServer needs a directory to store temporary files. You can define the directory to use in /fileserver/etc/main/main.cf. Furthermore, you can specify a maximum lifetime (in seconds) of temporary files in the directory.
<tempdir>tempdir</tempdir>
<tempfile>
<lifetime>3600</lifetime>
</tempfile>4.11.1. Maintenance Tasks
ReportServer performs certain maintenance tasks from time to time. You can define the interval (in ms) with which ReportServer will execute these.
<maintenance>
<tasks>
<interval>600000</interval>
</tasks>
</maintenance>ReportServer allows to define a timeout (in ms) for search queries:
<search>
<timeout>5000</timeout>
</search>4.12. Scheduler Settings
While scheduling new jobs, you can select the option ''Compress report'' if you want the report to be compressed in the email sent. Normally, this option is not selected by default. Now you can set this setting to be selected by default (in /fileserver/etc/main/main.cf):
<scheduler>
<email>
<defaultcompression>true</defaultcompression>
</email>
</scheduler>If you set this to true, ''Report compression'' will be automatically selected when scheduling new jobs. Defaults to false.
Refer to Section 4.4.2. Scheduler settings for more scheduler settings.
4.13. Localization Settings
ReportServer contains localization settings in the /fileserver/etc/main/localization.cf file.
You can configure the languages available to your ReportServer users with the following:
<locales>en,fr,de</locales>In the example above, english, french and german languages are enabled. The default language can be configured with the following setting:
<default>fr</default>In the example above, only french will be auto-selected in the ReportServer language list. Note that for users that previously used ReportServer, the language they used is saved in a cookie for next time, so the default language setting will not have any effect on these users. You have to delete your browser's cookies for this.
You can find more information on the available language codes here: https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Locale.html.
The country/region (note the uppercase) in which you are using your ReportServer can be configured as follows:
<region>US</region>This may be important when using currencies in your reports. For example, if your Jasper reports are executed using the ''DE'' (Germany) region code, their currencies will be printed in euro. If they are executed using the ''US'' region code, their currencies will be printed in dollars.
You can find more information on the available country/region codes here: https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Locale.html.
Formats can be configured in the following:
<format>
<!--
<shortDatePattern></shortDatePattern>
<longDatePattern></longDatePattern>
<shortTimePattern></shortTimePattern>
<longTimePattern></longTimePattern>
<shortDateTimePattern></shortDateTimePattern>
<longDateTimePattern></longDateTimePattern>
<numberPattern></numberPattern>
<currencyPattern></currencyPattern>
<integerPattern></integerPattern>
<percentPattern></percentPattern>
-->
</format>For example, the shortDatePattern and numberPattern may be configured as follows:
<format>
<shortDatePattern>y-MM-dd</shortDatePattern>
<numberPattern># ##0,00</numberPattern>
</format>Details on the formats available may be found here:
- Number Formats: http://www.gwtproject.org/javadoc/latest/com/google/gwt/i18n/client/NumberFormat.html
- Date Formats: http://www.gwtproject.org/javadoc/latest/com/google/gwt/i18n/client/DateTimeFormat.html
The currency locales may be configured in the following section:
<currencies>
<currency language="de" region="DE">currencyEuro</currency>
<currency language="en" region="US">currencyDollar</currency>
<currency language="en" region="GB">currencyPound</currency>
<currency language="ar" region="AE">AED</currency>
<currency language="ps" region="AF">AFN</currency>
...
</currencies>In the example above, the Euro currency is localized to the de_DE locale. If you need to change this, e.g. to fr_FR, you may change this to:
<currencies>
<currency language="fr" region="FR">currencyEuro</currency>
<currency language="en" region="US">currencyDollar</currency>
<currency language="en" region="GB">currencyPound</currency>
<currency language="ar" region="AE">AED</currency>
<currency language="ps" region="AF">AFN</currency>
...
</currencies>As currency is locale-specific, the format may change depending on the locale configured here.
For example, 123456.79 dollars will be printed as follows in the default locale:
US$123,456.79In en_US locale, the same will be printed as:
$123,456.79Note that you have to restart ReportServer if you change your currency locale configuration.
More details on currency locales may be found here: http://www.gwtproject.org/javadoc/latest/com/google/gwt/i18n/client/NumberFormat.html.