Support

Lorem ipsum dolor sit amet:

24h / 365days

We offer support for our customers

Mon - Fri 8:00am - 5:00pm (GMT +1)

Get in touch

Cybersteel Inc.
376-293 City Road, Suite 600
San Francisco, CA 94102

Have any questions?
+44 1234 567 890

Drop us a line
info@yourdomain.com

About us

Lorem ipsum dolor sit amet, consectetuer adipiscing elit.

Aenean commodo ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Donec quam felis, ultricies nec.

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: false

If 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_mixed

The 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:
  • databaseProductName: the database product, e.g. ''MySQL'', ''H2'', etc.
  • databaseProductVersion: the version of the database, e.g. ''8.0.31''
  • driverName: the JDBC driver, e.g. ''MySQL Connector/J''
  • driverVersion: the JDBC driver's version: ''mysql-connector-j-8.0.31''
  • JDBCMajorVersion: the JDBC major version of the driver
  • JDBCMinorVersion: the JDBC minor version of the driver
  • URL: the datasource's complete JDBC URL
  • userName: the datasource's JDBC username
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 adminviews tags and tabs for the TeamSpace are put within the objectinfo 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&amp;format=html&amp;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 true

As 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.html

As 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 true

To see that everything worked, we use the following simple script which simply outputs the parameter user:

def user = httpRequest.getParameter('user')
return user

Note 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.AuthenticatorService

In 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.UserPasswordPAMAuthoritative

The 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.UserPasswordAuthToken

The 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 User Information 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:

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.79

In en_US locale, the same will be printed as:

$123,456.79

Note 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.

4.14. Security related properties

In the following section we describe certain security related configuration options.

In /fileserver/etc/security/misc.cf you can define a blacklist for ReportServer expressions. If not running ReportServer with a SecurityManager, you should ensure that such expressions cannot use java reflection. At a minimum level you should deny the phrase getClass. Further information can be found in the administration and user guides.

<juel>
	<expression>
		<blacklist>getClass</blacklist>
	</expression>
</juel>

In the example the expression getClass is prohibited. Multiple expressions are comma separated.

4.14.1. URL Whitelist

Certain operations, e.g. redirect, are not allowed for external URLs. If you need to allow a URL you can add it to the whitelist in the /fileserver/etc/security/whitelist.cf configuration file.

<urls>
	<url>http://www.host.com</url>
</urls>

4.14.2. Configuring error message level of detail

Further, in this configuration file, you can select the level of detail of error messages shown to the user. Currently, the following is supported:

  • hideViolatedSecurityExceptionDetails: When a security rule is violated, e.g. when a user tries to execute a report the user is not allowed to, specific details of the security violation are being printed to the user by default. This includes the specific security target, the rights/permissions being violated, the objects and the method where this happens, if available. This helps administrators to exactly understand which rights/permissions are needed for a specific object to be accessed by a user. If not desired, you can set this to false in order to hide these specific details from the user, which may be preferable in some cases. Defaults to false.

Below you can see an example configuration.

<errorMessages>
   <hideViolatedSecurityExceptionDetails>false</hideViolatedSecurityExceptionDetails>
</errorMessages>

4.14.3. Disabling forgot password

If you wish to disable the ''forgot password'' option in the login window, you can set the 'disableLostPassword'' option to true.

Below you can see an example configuration for this.

<disableLostPassword>true</disableLostPassword>

4.14.4. Configuring cryptography

The file /fileserver/etc/security/crypto.cf defines various cryptography related options. The <cryptocredentials> section defines how cryptographic credentials, such as private keys and certificates are retrieved for various ReportServer modules.

To do so, a provider is specified for each module.

A provider is defined by specifying the name of the handler-class and some additional attributes.

<provider type="signature">
	<class>
		net.datenwerke.rs.incubator.service.crypto.FileServerKeyStoreKryptoCredentialProvider
	</class>
	<alias>rs</alias>
	<secret>secret</secret>
	<type>jks</type>
	<location>/fileserver/keystore.jks</location>
</provider>

This configures the default handler, which tries to load key-material from a file within the fileserver. Providers can be specified for these types:

signature: a keystore that holds the private key, ReportServer uses when sending signed emails

user: a keystore that holds public keys and certificates of ReportServer users. This is used, when sending encrypted emails. An alternate method to provide key material is by using a custom script, that retrieves the keys e.g. from a corporate directory.

4.14.5. Specifying a Password Policy

ReportServer allows to configure the use of password policies to ensure that users choose secure passwords. The corresponding configuration goes into the configuration file /fileserver/etc/security/passwordpolicy.cf.

For example, you can define how long passwords should be and define character classes from which the password must be built. Furthermore, you can define how often passwords need to be changed and when a previously chosen password may be chosen again.

<pswd>
	<maxage>32</maxage>
	<minage>1</minage>
	<minlength>8</minlength>
</pswd>

The parameter maxage defines the number of days a password remains valid. The parameter minage denotes that a password may be changed at most every day. Minlength defines the minimal length of passwords.

The property <historysize>6</historysize> denotes that the last 6 passwords may not be used when changing the password.

You can define a threshold on the number of failed login attempts after which a user account is blocked. This is done using <lockoutthreshold>3</lockoutthreshold>. <lockoutresettimeout> 60</lockoutresettimeout> specifies the time after wich automatically locked accounts can be used again.

The <characterset> definitions specify which characters for a password are approved and how many characters from a particular group must be used.

<characterset>0123456789</characterset>
<choosemin>2</choosemin>
<characterset>abcdefghijklmnopqrstuvwxyz</characterset>
<choosemin>1</choosemin>
<characterset>ABCDEFGHIJKLMNOPQRSTUVWXYZ</characterset>
<choosemin>1</choosemin>
<characterset>!$
<choosemin>2</choosemin>

In the above example, it is specified that from the first and last group (the digits and special characters) at least 2 characters must be used. From the two remaining groups at least a single character must be used.

Note that the specified number denotes a lower bound on the characters chosen from this group.

A complete configuration of the password policy might thus look as follows:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
	<rs>
		<security>
			<passwordpolicy>
				<bsipasswordpolicy>
					<pswd>
						<maxage>32000</maxage>
						<minage>1</minage>
						<minlength>8</minlength>
					</pswd>
					<historysize>6</historysize>
					<lockoutthreshold>3</lockoutthreshold>
					<lockoutresettimeout>60</lockoutresettimeout>
					<characterset>0123456789</characterset>
					<choosemin>1</choosemin>
					<characterset>abcdefghijklmnopqrstuvwxyz</characterset>
					<choosemin>1</choosemin>
					<characterset>ABCDEFGHIJKLMNOPQRSTUVWXYZ</characterset>
					<choosemin>1</choosemin>
					<characterset>!$
					<choosemin>1</choosemin>
				</bsipasswordpolicy>
			</passwordpolicy>
		</security>
	</rs>
</configuration>

4.14.6. Customizing the Logout URL

By default, when a user logs out, the user will be taken back to the original ReportServer login page. In order to change this, you can change the config file located in etc/security/misc.cf within the ReportServer filesystem.

An example of this is shown below.

<logout>
     <url>http://your-reportserver/ReportServer/reportserver/fileServerAccess?path=/resources/public/login.html</url>
</logout>

The example above redirects the user to the given URL instead of the origianl ReportServer login page.

This is useful when customizing the login page, you can find more details on customizing the login page on Section 4.4.2. Customization of the Login Page.

4.14.7. Notifications

Users can be notified when their password has been created the first time or when their password was changed (by an administrator). The notification is done via email (note that for this the mail server must be correctly configured). For this purpose, the following configuration file is available: security/notifications.cf.

This configuration file allows to configure the texts sent by email and further allows to disable this functionality, if desired.

<createdpassword disabled="false">
	<email>
		<subject>Email Subject</subject>
		<text>Email Text
			Username: ${user.getUsername()}
		</text>
    </email>
</createdpassword>
<changedpassword disabled="false">
	<email>
		<subject>Email Subject</subject>
		<text>Email Text
			Username: ${user.getUsername()}
		</text>
	</email>
</changedpassword>

The following substitutions are available.

Expression Description
${user.getUsername()} username
${user.getFirstname()} user's first name
${user.getLastname()} Last name of user
${user.getEmail()} user's email address
${user.getTitle()} user's title
${user.getId()} user's id

Further, this file allows to configure the texts of the email sent by the listlogfiles terminal command using the -e option.

<logfiles>
	<email>
		<subject>Email Subject</subject>
		<text>Email Text
			Filter: ${filter}
		</text>
	</email>
</logfiles>

In this section, the following substitutions are available. For more information, check the listlogfiles documentation.

Expression Description
${filter} filter passed with -f parameter
${user.getUsername()} username
${user.getFirstname()} user's first name
${user.getLastname()} Last name of user
${user.getEmail()} user's email address
${user.getTitle()} user's title
${user.getId()} user's id

Note that as of RS 3.3.0 the old lostpassword.cf configuration file is no longer available. This configuration is now done in the new notifications.cf file.

4.14.8. User activation

Users can be activated by administrators using the user manager. On activation, the user will receive an email with an automatically generated (single use) password (note that for this the mail server must be correctly configured). After the first login, the user must change the password according to the password policy.

You can customize the email sent to the user in the configuration file /fileserver/etc/security/activateuser.cf.

<security>
	<activateaccount>
		<email>
			<subject>Your ReportServer account details</subject>
			<text>
				Username: ${user.getUsername()}
				Password: ${password}
			</text>
		</email>
	</activateaccount>
</security>

The following substitutions are available.

Expression Description
${user.getUsername()} username
${user.getFirstname()} user's first name
${user.getLastname()} Last name of user
${user.getEmail()} user's email address
${user.getTitle()} user's title
${user.getId()} user's id
${password} the generated password
${url} the URL under which ReportServer can be accessed

4.14.9. Configuring the SFTP Server

ReportServer Enterprise Edition can be configured to expose its internal filesystem (and other management areas) using an SFTP server. The corresponding configuration goes into /fileserver/etc/misc/misc.cf.

remoteaccess>
	<sftp disabled="false">
	    <!-- Use $generated in order to generate a key on first start. -->
		<keylocation>/path/to/hostkey.pem</keylocation>
		<port>8022</port>
	</sftp>
</remoteaccess>

The SFTP server can be disabled if you don't need it via the disabled property. After a ReportServer restart, it will not be started if disabled previously.

The file hostkey.pem should contain the server's certificate. You can also use $generated in order to generate a key on first start. The path should be an absolute path (e.g., file:///C:/path/to/hostkey.pem in Windows or /path/to/hostkey.pem in Unix.) Note that the file:// protocol is necessary in Windows in order to recognize C as the beginning of an absolute path.

Note that changes will only take effect after restarting ReportServer. If you do not want to start the SFTP server simply supply an invalid path or $generated and disable it with disabled.

4.15. SSO related properties

In the following section we describe SSO configuration options.

4.15.1. LDAP

LDAP-related properties, described below, are defined in the /fileserver/etc/sso/ldap.cf configuration file. These are relevant for the ''ldapimport'' terminal command and the ldapimport.groovy script available here: https://github.com/infofabrik/reportserver-samples/blob/main/src/net/datenwerke/rs/samples/admin/ldap/ldapimport.groovy.

Note that you can (and should) test your LDAP configuration with the ldaptest commands described in the Administration Guide for checking your LDAP configuration before letting the real import to happen. The ldapschema, ldapguid, ldapfilter and ldapinfo terminal commands may also be useful for exploring your LDAP server and also the extended the ldaptest users, ldaptest groups and ldaptest organizationalUnits with a -s (schema) flag. While the -s flag allows you to explore the installed object class types of your users', OUs' and groups' object classes, the ldapschema allows you to explore any object class. For example, you may execute ldaptest users -s for printing the schema of the users' object class. You should get a list of optional attributes, required attributes, and the parent object class. Suppose the parent's object class is ''organizationalPerson''. You may then explore this object class with ldapschema objectClassInfo organizationalPerson. You may continue exploring the LDAP schemas until the top-most object class: top.

<disabled>true</disabled>
<provider>
   <host>directory.example.com</host>
   <port>389</port>
</provider>

The disabled property allows you to completely disable your LDAP if you don't need it. Note that LDAP is disabled by default.

The provider property configures the host (or IP) and port where your LDAP server is installed. Note that if you use SSL (LDAPS) this port is different than the LDAP port. StartTLS uses the same LDAP port.

<security>
   <encryption>none</encryption>
   <principal>CN=ldaptest,CN=Users,DC=directory,DC=example,DC=com</principal>
   <credentials>password</credentials>
</security>

The encryption property defines the encryption protocol to use. Valid values are none (for no encryption), starttls (for StartTLS encryption (recommended)) and ssl (for SSL (LDAPS) encryption).

In order for encryption to work, you have to install the certificates needed for these to be trusted by ReportServer.

This means that you must add the LDAP server's certificate (or a certificate higher up the trust chain) to a truststore that is known to ReportServer during startup.

This can be achieved in two different ways:

  • Passing the truststore where the certificate is installed. If you use JKS keystores you can pass the keystore analogous to: -Djavax.net.ssl.trustStore=/path/to/security/truststore.jks -Djavax.net.ssl.trustStorePassword=myTrustStorePassword -Djavax.net.ssl.trustStoreType=JKS If you use PKCS12 you can pass the keystore analogous to: -Djavax.net.ssl.trustStore=/path/to/security/truststore.p12 -Djavax.net.ssl.trustStorePassword=myTrustStorePassword -Djavax.net.ssl.trustStoreType=PKCS12 Refer to the Java Documentation for details: https://docs.oracle.com/en/java/javase/11/security/java-secure-socket-extension-jsse-reference-guide.html Be aware that if you use this method, you may need to add other certificates as well in order for your Email, SFTP, OneDrive, etc to continue working, as these certificates are contained in the cacerts truststore, see below. You may of course create a copy of cacerts and add your certificates to this copy instead of using the java cacerts truststore directly.
  • Or installing the certificate into your JVM trust store (usually located here java-home/lib/security/cacerts). Refer to the Java Documentation for details: https://docs.oracle.com/en/java/javase/11/security/java-secure-socket-extension-jsse-reference-guide.html.

 

You can test your SSL configuration, i.e. if your certificate was installed correctly, with the ssltest terminal command. Check the Administration Guide for details.

The principal and credentials properties allow you to authenticate to your LDAP server.

<base>OU=EXAMPLE,DC=directory,DC=example,DC=com</base>
<filter>
<![CDATA[
(|(objectClass=organizationalUnit)(objectClass=user)(objectClass=group))
]]>
</filter>

The base property defines the address of the root object in the LDAP directory. All objects are stored below the base.

The filter allows you to retrieve a subset of all the nodes found below the base DN.

You can analyze your installed LDAP filter with the ldapfilter terminal command. You can test your installed LDAP filter with the ldaptest filter terminal command. Check the Administration Guide for details on both commands.

<externalDir>/usermanager/external</externalDir>
<writeProtection>true</writeProtection>
<logResultingTree>false</logResultingTree>
<flattenTree>false</flattenTree>

The externalDir property defines the directory in ReportServer where your users/groups and OUs will be imported into. These objects will be write-protected if the writeProtection is set to true.

When the logResultingTree property is set to true, a summary and some statistics of the changes done in your ReportServer are logged into your logs.

If you need to import all nodes into the root directory (i.e. into the externalDir directory described above) instead of using the original LDAP tree, you can set flattenTree to true. Note that all OUs will be empty in this case. If you don't want to include the empty OUs, you have to remove them via the filter attribute.

<attributes>
   <objectClass>objectClass</objectClass>
   <guid>entryUUID</guid>
   <organizationalUnit>
      <objectClass>organizationalUnit</objectClass>
      <name>name</name>
   </organizationalUnit>
   <group>
      <objectClass>group</objectClass>
      <name>name</name>
      <member>member</member>
   </group>
   <user>
      <objectClass>inetOrgPerson</objectClass>
      <firstname>givenName</firstname>
      <lastname>sn</lastname>
      <username>sAMAccountName</username>
      <mail>mail</mail>
   </user>
</attributes>

The properties above define the attributes used in your AD nodes. In order to browse and analyze the LDAP schema of your LDAP installation, you can use the following commands: ldapschema, ldapinfo, and ldapguid. Check your Administration Guide for details.

General object class attributes are defined by the attributes - objectClass attribute, while object GUIDs are defined by the guid attribute. Note that GUIDs must be unique. ReportServer makes a best-effort guess of the appropriate GUID for your installation with the ldapguid terminal command. Check your Administration Guide for details.

The organizationalUnit - objectClass defines a OU with name specified by organizationalUnit - name. The same applies to the group attributes.

The user attributes specify a given user. The node is determined as a user by the user - objectClass attribute, while the firstname, lastname, username and mail attributes allow ReportServer to fetch these attributes from a user node.

<attributes>
   <additional>
      <attribute>department</attribute>
      <attribute>office</attribute>
   </additional>
</attributes>

If you need additional attributes, i.e. attributes not included in the standard attribute list, you can fetch them from your LDAP by defining them in the additional list as shown above. The example would fetch the department and office attributes, which can be then used in a LdapNodePostProcessHook hooker as shown in this example: https://github.com/infofabrik/reportserver-samples/blob/main/src/net/datenwerke/rs/samples/admin/ldap/ldapUserVariableProcessorHooker.groovy. The example uses the department LDAP attribute in order to set the appropriate value into a given user-variable myUserVar.

Note that the old allowLocalUsers setting was removed as of ReportServer 4.5.0. Instead, you should use colon-separated PAMs in your reportserver.properties as explained in the Script Guide (Custom Authenticators PAMs) if you need to allow/disallow local users to log-in. E.g. the following setting allows only LDAP users: rs.authenticator.pams = net.datenwerke.rs.ldap.service.ldap.pam.LdapPAM while the following setting allows both LDAP and local users: rs.authenticator.pams = net.datenwerke.rs.ldap.service.ldap.pam.LdapPAM:net.datenwerke.rs.authenticator.service.pam.UserPasswordPAM

InfoFabrik GmbH

Wir wollen, dass alle Unternehmen, Institutionen und Organisationen, die Daten auswerten, selbständig und zeitnah genau die Informationen erhalten, die sie für ein erfolgreiches Arbeiten benötigen.

InfoFabrik GmbH
Klingholzstr. 7
65189 Wiesbaden
Germany

+49 (0) 611 580 66 25

Kontaktieren Sie uns

Was ist die Summe aus 5 und 3?
Copyright 2007 - 2024 InfoFabrik GmbH. All Rights Reserved.

Auf unserer Website setzen wir Cookies und andere Technologien ein. Während einige davon essenziell sind, dienen andere dazu, die Website zu verbessern und den Erfolg unserer Kampagnen zu bewerten. Bei der Nutzung unserer Website werden Daten verarbeitet, um Anzeigen und Inhalte zu messen. Weitere Informationen dazu finden Sie in unserer Datenschutzerklärung. Sie haben jederzeit die Möglichkeit, Ihre Einstellungen anzupassen oder zu widerrufen.

Datenschutzerklärung Impressum
You are using an outdated browser. The website may not be displayed correctly. Close