Overview

1. The following upgrade installation gives a step by step description of how to upgrade the Bitnami ReportServer Stack to either ReportServer 3.7.1 Community Edition or ReportServer 3.7.1 Enterprise Edition. Another versions can be upgraded in an analogous way. The upgrade consists of the following steps.

   1. Obtain the Bitnami ReportServer Enterprise (or Community) stack
   2. Stop the old ReportServer
   3. Create a complete backup of Reportserver data and a DB backup
   4. Install the new Bitnami ReportServer stack
   5. Delete the internal db of your ReportServer stack
   6. Import the backup data
   7. Restart ReportServer
   8. Check the logs
   9. Update the password of the new database

   Before you start with upgrading the ReportServer Bitnami Stack, please make sure to have the following requirement met.

   • You need to have a Bitnami Installation of Reportserver of version 3.0.3 or higher for this to work. In this example we upgrade 3.1.0 to version 3.7.1. Another versions can be upgraded in an analogous way.

Obtaining the Bitnami ReportServer stack

The first step is to download the updated Bitnami ReportServer Stack. You can find download links on our download page. Note that you can upgrade both to ReportServer Enterprise or to ReportServer Community. Once you have downloaded the installer, keep the file in a safe location and proceed with the next steps without starting the installation process. We'll do so in just a moment, but before that we need to make sure that the following precautions have been made for a succesful transfer of data.

• A complete DB-backup of your current bitnami reportserver metadata database including all relevant tables and data. Be sure you can return to the previous state in case something goes wrong.
• All relevant files of your current installation (any drivers you may use, reportserver.properties, web.xml if you changed the default one, etc). In the bitnami installation you can find the external configuration directory here:
  • E.G. for standard installation: C:\Bitnami\reportserverenterprise-3.7.1.6048-1\apps\reportserver\reportserver-conf

The easiest and most complete backup is a complete SNAPSHOT of your current installation. Be sure you can return to the previous state in case something goes wrong.

Please make sure that you have access to a terminal (Linux) or cli (Windows command prompt) and that you have a user with administration rights.

Install the new Bitnami ReportServer Stack

In this guide we describe how to upgrade ReportServer installations to the latest ReportServer 4.7 version. This upgrade guide is valid for ReportServer installations 3.0.1 and higher. This tutorial is valid both for Enterprise and Community versions, as well as for manual installations and Bitnami installer installations.

If you want to perform a new installation check here: Linux or Windows.

Backup all your data before upgrading.

In order to use ReportServer 4.7 with Oracle, the following jars (or newer versions) are needed: ojdbc6.jar, orai18n.jar, xdb6.jar and xmlparserv2.jar. These are needed because of the new XML/JSON support. Please download and copy them to the WEB-INF/lib directory. Note: we recommend to use ojdbc7.jar or newer because of this jdbc driver incompatibility with null parameters in BIRT reports.

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 finding out these configuration files, check the Administration Guide for details. Note that default values are used for configuration files that are not found.

The Upgrade in a Nutshell

The upgrade basically consists of replacing the webapp files of ReportServer, that is, the files under TOMCAT/webapps/reportserver (or TOMCAT/webapps/ROOT, depending on your installation) are removed and the freshly downloaded files are copied there instead. In the following we explain the upgrade in detail

Preconditions

In this upgrade guide we assume that you are working with an externalized configuration directory as described in Chapter 5 of the configuration guide. We are also assuming that you use Tomcat as application server. If you are not yet using an external configuration directory, this is a good point to change your setup. As for this upgrade, the main difference is that you do not need to worry about your configuration changes, but can simply do a one-step copy and paste upgrade.

For Bitnami users: We here describe how to upgrade ReportServer without upgrading the entire Bitnami stack.

The Upgrade

To upgrade ReportServer, follow these steps.

1. Download the newest version of ReportServer 4.7
2. Stop your ReportServer instance.
3. Go to the webapps directory of Tomcat and there to the directory in which ReportServer is installed. If you used the Bitnami installer this is

If you followed the installation tutorial this would be

To check that you have the right folder confirm that this folder contains amongst others a file called ReportServer.html and a folder called ddl.

1. Clear out the above folder, that is, remove the entire contents. If you do not use external configuration, all your drivers will be deleted, since the whole directory is being replaced by the downloaded one. Backup them to easily add them later. These are found on the WEB-INF/lib directory of your reportserver installation.
2. Unzip ReportServer and copy everything to the now empty folder. The structure should be identical to before, that is, you should once more find a file called ReportServer.html and a folder called ddl.
3. Completely delete your browser's cache (including all temporary internet files!!!) to ensure you will get the newest files. If you get any error of this type: "Type 'net.datenwerke.rs.base.client.dbhelper.dto.DatabaseHelperDto' was not assignable to 'com.google.gwt.user.client.rpc.IsSerializable' and did not have a custom field serializer.For security purposes, this type will not be serialized.: instance = net.datenwerke.rs.base.client.dbhelper.dto.DatabaseHelperDto@62cbf40f at com.google.gwt.user.server.rpc.impl.ServerSerializationStreamWriter.serialize(ServerSerializationStreamWriter.java:667)" you have to delete all browser's cache including all temporary internet files.
4. Start up Tomcat

This completes the Upgrade to the latest ReportServer 4.7 version. To ensure that installation was successful have a look at your Tomcat log files. Startup should look similar to the following

The important parts are the last rows which indicate that the database upgrade script was successfully executed. Note that this only happens once after the upgrade and that from then on any startup would show an updated schema version, that is:

Adapt Internal Configuration

An optional step is to adapt the internal configuration files located in ReportSever's file server (folder etc). For an overview of the changes see here.

Upgrade/Install Demo Data

A final optional step is to install or upgrade your existing demo data. For this, check this link. This step will delete all your existing data in the system.

Happy Reporting

In this guide we describe how to upgrade ReportServer 2.2.2 (RS2.2.2-5639) installations to ReportServer 3.0.1. This guide assumes that you have installed ReportServer manually and have not setup ReportServer via the Bitnami ReportServer Stack. A separate upgrade guide is available for the Bitnami ReportServer Stack.

Before we continue, make sure that you have a backup of the system including your ReportServer database.

With ReportServer 3.0.1 we have introduced some changes in licensing and now provide two versions of ReportServer: ReportServer Community Edition and ReportServer Enterprise Edition. In the cause of this restructuring we have moved some of the functionality that was previously available in the Open Source version of ReportServer to ReportServer Enterprise (see a detailed comparison between the two versions). In particular, scripting is no longer available in the open source variant of ReportServer. A trial version of ReportServer Enterprise Edition including full scripting capabilities is available on request from mailto:sales@infofabrik.de

If you require any of the following features and do not wish to purchase ReportServer Enterprise Edition, please do not upgrade to Reportserver 3.0.1: Scripting, Dynamic List Templates, Dynamic List Pivot Mode, SAP Crystal, Database Bundles or Conditional Scheduling: click here for a detailed comparison between ReportServer Enterprise and ReportServer Community.

Overview

The following upgrade installation explains how to upgrade to either ReportServer 3.0.1 Community Edition or ReportServer 3.0.1 Enterprise Edition. The upgrade consists of the following steps.

1. Obtain the ReportServer Program Files
2. Replace the Tomcat webapp with the new version of ReportServer.
3. Adapt the external configuration files
4. Create the Schema Info table
5. Start ReportServer for an automated upgrade of the database schema

Obtaining the ReportServer Program Files

The binaries for ReportServer Community Edition are available from SourceForge. On SourceForge look for Files and then the bin directory. Beneath the bin directory you should find directories for the various versions of ReportServer. The files are named according to the following schema: RS followed by the version number and the build number, followed by reportserver.zip. For example, RS3.0.1-5834-2016-03-24-23-46-15-reportserver-ce.zip denotes ReportServer version 3.0 minor revision 1 and build number 5834.

Note: You can download a trial version of the latest ReportServer Enterprise Edition here.

Download the new program files to a temporary location. We will refer to the zip archive as REPORTSERVER301.ZIP.

Replace the Program Files

As a first step we need to replace the ReportServer program files. In the following we assume that Tomcat has its webapps directory in TOMCAT_WEBAPPS. In a standard installation, ReportServer is installed in a folder TOMCAT_WEBAPPS/reportserver or in case you decided to install it to be directly accessible it is installed in TOMCAT_WEBAPPS/ROOT. In the following we will refer to the ReportServer installation directory as REPORTSERVER_WEBAPPS_DIR.

To upgrade the program files perform the following steps:

Stop Tomcat

Make sure that the Tomcat server is stopped.

Remove old files

Move everything beneath REPORTSERVER_WEBAPPS_DIR to a temporary directory, such that we can later access old configuration files.

Unzip the new Program Files to REPORTSERVER_WEBAPPS_DIR

Unzip the new program files (REPORTSERVER301.ZIP) to REPORTSERVER_WEBAPPS_DIR. Ensure that the files were extracted to the correct folder. For this check that directly beneath REPORTSERVER_WEBAPPS_DIR there are (amongst others) the folders WEB-INF and ddl.

Adapt External Configuration

In the next step we need to adapt the external configuration. For this we need to configure two configuration files:

• reportserver.properties — contains ReportServer specific properties
• persistence.properties — contains the connection properties for ReportServer

Note that the connection properties in previous versions were defined via a file called persistence.xml. Starting with ReportServer 3.0.1 the connection properties are instead defined via the configuration file persistence.properties.

reportserver.properties

You can safely reuse your old version of the configuration file reportserver.properties. Simply copy the old file to REPORTSERVER_WEBAPPS_DIR/WEB-INF/classes.

persistence.properties

The configuration persistence.properties defines the connection properties used by ReportServer. An example configuration file called persistence.properties.example is provided in directory REPORTSERVER_WEBAPPS_DIR/WEB-INF/classes. Rename the persistence.properties.example to persistence.properties and set the following properties according to your database settings:

You can find the correct configuration values from your old configuration file persistence.xml which is located in REPORTSERVER_OLD_TMPDIR/WEB-INF/classes/META-INF.

Please ensure that the hibernate.dialect is one of the supported ReportServer dialects. These differ from the standard hibernate settings. The supported dialects are:

• net.datenwerke.rs.utils.hibernate.DB2Dialect
• net.datenwerke.rs.utils.hibernate.MySQL5Dialect
• net.datenwerke.rs.utils.hibernate.PostgreSQLDialect
• net.datenwerke.rs.utils.hibernate.Oracle10gDialect
• net.datenwerke.rs.utils.hibernate.SQLServer2008Dialect

Tip: ReportServer allows to remove the configuration files from Tomcat's web directory and put them into an external configuration directory. This makes future upgrades easier as upgrading the program files then does not overwrite any configuration. For further information on using an external configuration directory see the chapter on the configuration dir in ReportServer's Configuration Guide as well as the best-practice installation guide.

Create Schema Info Table

Next, we need to perform a small schema update to tell ReportServer what version of the schema is currently used. This step will only be necessary for this upgrade. Connect to your database and issue the following create tabel statement.

We now need to insert a single line identifying the current schema version. If you have the latest version from source forge installed, then this would be RS2.2.2-5639.

In this best-practice guide we discuss step-by-step how to manually install ReportServer on a freshly set-up Ubuntu box (Version 22.04). While we have chosen Ubuntu as the underlying operating system we hope that this guide also helps with setting up ReportServer on different operating systems. If you would rather use a preconfigured installation package, have a look at the docker images available from our download page.

In this guide we discuss how to install ReportServer. This instruction is valid both for ReportServer Community Edition and for ReportServer Enterprise Edition (see here for a detailed comparison).

Overview

ReportServer is a database backed Java web application and thus to install ReportServer we additionally need to install Java, a servlet container (in this guide we choose Tomcat) and a database (in this guide we choose PostgreSQL). Thus, a high-level overview of an installation of ReportServer consists of the following steps.

1. Obtaining the ReportServer binaries
2. Installation of Java
3. Installation of Tomcat
4. Installation of PostgreSQL
5. Setting up ReportServer

Obtaining the ReportServer Binaries

The binaries for ReportServer Community Edition are available from SourceForge. On SourceForge look for Files and then the bin directory. Beneath the bin directory you should find directories for the various versions of ReportServer. At the time of writing, the latest version is ReportServer 4.7. Download the latest version (the file should be named RS followed by the version number and the build number, followed by reportserver.zip). For example, RS4.7.2-6108-reportserver.zip denotes ReportServer version 4.7.2 build number 6108.

To obtain a trial version of ReportServer Enterprise Edition go to our download page and look for Binaries.

Go to your home directory (or some directory where we can store the binaries for now) and download ReportServer via https://sourceforge.net/projects/dw-rs/files/latest/download

Note that you need to adapt the version number. We will get back to the binaries in a moment. First, let's install Java, Tomcat and PostgreSQL.

Installing Java

For a smooth experience it is best to install Oracle Java or OpenJDK (via repository) or Azul Zulu Builds of OpenJDK (https://www.azul.com/downloads/?version=java-11-lts&os=ubuntu&architecture=x86-64-bit&package=jre).

If java has been installed successfully, then a call to java -version should print out the installed java version.

Installing Tomcat

In the following we install Apache Tomcat a web application server that is well suited to run ReportServer. To install Tomcat (currently Ubuntu has precompiled packages for tomcat9 (Tomcat 10 is not supported by ReportServer at the moment)) issue the following command

Next, we need to configure Tomcat and tell it to invoke java. On Ubuntu you can find these options in the configuration file /etc/default/tomcat9. Open this file with your favorite editor (e.g. nano) and look for the setting for JAVA_OPTS. This tells Tomcat how to invoke java. In particular you should set the options -Xmx4g (which will set the memory of Tomcat and thus ReportServer to 4 GB), -Dfile.encoding=UTF8 (to use UTF-8 by default) and -Drs.configdir=/opt/reportserver (to configure ReportServer's config dir; we will see the effect of this later). Thus, you could have the following configuration:

If you use Java 11 or newer, (ReportServer currently supports Java 11 and Java 17), you need some extra configuration which can be done in the setenv.sh of your Tomcat environment ( /usr/share/tomcat9/bin/setenv.sh). Specifically, the following configuration is needed:

By default the Tomcat web server will listen on port 8080. Standard web applications are, however, usually run on port 80. To allow serving ReportServer directly on port 80, you can either configure a reverse proxy (e.g. via Apache) or, as we will explain next, configure Tomcat to use authbind. You can't use port 80 because ports under 1024 are restricted to root access in Linux (and we don't want that für our Tomcat) unless you use authbind to override that restriction. First ensure that the authbind packages are installed:

Next we go to authbind's byport directory, and create files for the port 80 which we also give to the Tomcat user. This user was automatically created at the process of installing tomcat "apt-get install tomcat":

Next step, modify systemctl to use AUTHBIND when starting the tomcat

Finally, we need to change Tomcat's default connector configuration to listen on port 80. For this change the connector settings in server.xml.

Tomcat should now be properly configured and you can give it a test spin. Reload the systemd manager configuration (because of our ExecStart change) and restart Tomcat via

Make sure that you can connect to Tomcat on port 80 by simply pointing your browser to

where YOUR_IP is the server's IP address (for example, 127.0.0.1, if you are on the same machine). If Tomcat is running properly, stop it again via

Installing PostgreSQL

Having installed Tomcat, we next need to install a database to hold ReportServer's metadata. For this we will use PostgreSQL in this guide. At the time of writing the latest prepackeged Ubuntu packages is for PostgreSQL 14.5.

Install PosgreSQL via

Next we setup a password for the postgres main user (called postgres). For convenience we here assume that the password is set to postgres

Press CTRL+D (corresponds \q) to leave the command prompt.

Next, we create a database called reportserver which will serve as the metadata storage for ReportServer. For run

To set up a database user for reportserver (with password reportserver) run

Next we need to grant user reportserver the necessary privileges. For this we run

Finally, since PostgreSQL on Ubuntu per default only allows to connect locally via the postgres user, we need to adapt the configuration file /etc/postgresql/14/main/pg_hba.conf. Here look for a line containing

and replace it by

Which allows users that provide a valid password hash to connect. For the changes to take effect we need to restart the postgres service.

Setting up ReportServer

Now that we have Tomcat and PostgreSQL set up, we can install and configure ReportServer. Let REPORTSERVER.zip denote the zip file that we downloaded in the very first step. If not already present let's install unzip.

Next, remove the folder ROOT beneath Tomcat's webapp folder. This is where afterwards we are going to put ReportServer in.

Now unzip RS4.7.VERSION-reportserver-ce.zip to that directory. But before executing, change MYUSER to your user or the path to the directory where you stored the downloaded zip-file.

In the next step we will create a configuration directory for ReportServer. Remember that when we configured Tomcat, we set the environment variable JAVA_OPT to contain the option -Drs.configdir=/opt/reportserver. This tells ReportServer to look for its configuration directory in /opt/reportserver. Let's create that directory as well as the sub-directories lib and config.

The lib directory can hold additional jars (for example, additional JDBC drivers). The config directory can hold internal configuration files. For further information about the config dir see the chapter on the configuration dir in ReportServer's Configuration Guide.

In a next step we will copy default configuration files to the configuration directory. We will copy the following files.

• persistence.properties.example
• reportserver.properties
• logging-rs.properties

Note that we have renamed "persistence.properties.example" into persistence.properties. This file holds the database configuration which we setup next. For this open the file persistence.properties with a text editor and set up the following connection parameters

Having changed the configuration, let's give the tomcat user the necessary permissions to read the configuration files.

The same applies for tomcat webapps.

Initialize the ReportServer Database

ReportServer expects that its database is properly initialized. For this we need to run the DDL script for PostgreSQL that is located in the ddl subdirectory of ReportServer (i.e., in /var/lib/tomcat9/webapps/ddl). ReportServer supports various databases and in that directory you not only find the create script for PostgreSQL but also for all other supported databases. The files are named according to the following format:

reportserver-VERSION-schema-PostgreSQL_CREATE.sql

Besides a CREATE script there is also a DROP script, if you wish to clean up the database.

To set up ReportServer's database run the following command to run the CREATE ddl:

If you run the ddl script via a database GUI make sure to call commit.

Setup Logging

By default, Tomcat will write its log entries into a file called catalina.out, which not only contains ReportServer specific entries but anything that involves Tomcat. To have a ReportServer specific log file, edit the file /var/lib/tomcat9/conf/logging.properties. The following changes need to be made:

• add 5reportserver.org.apache.juli.FileHandler to handlers
• define handler specific properties
• tell tomcat to use the new handler for anything ReportServer specific
• adapt the log format to include a proper timestamp

A sample configuration could look as follows:

Starting ReportServer

We are finally at an end. To test the installation, start tomcat and observe the output in ReportServer's log file.

If all goes well you should see a message such as:

You can now direct your browser to

and log in to ReportServer via user root with password root which ReportServer created on the first start.

Happy Reporting

In this best-practice guide we discuss step-by-step how to manually install ReportServer on a freshly set-up Windows 10 box. If you would rather use a preconfigured installation package, have a look at the installer packages available in our download page.

The instructions in this guide are valid both for ReportServer Community Edition and for ReportServer Enterprise Edition (see here for a detailed comparison).

Overview

ReportServer is a database backed Java web application. In order to install ReportServer we additionally need to install Java, a servlet container (in this guide we choose Tomcat) and a database (in this guide we choose MariaDB). Thus, a high-level overview of an installation of ReportServer consists of the following steps.

1. Overview
2. Obtaining Binaries
3. Install Java
4. Install Tomcat
5. Install MariaDB
6. Setup ReportServer
7. Setup Database
8. Setup Logging
9. Start ReportServer

Obtaining the ReportServer Binaries

The binaries for ReportServer Community Edition are available from SourceForge. On SourceForge look for Files and then the bin directory. Beneath the bin directory you should find directories for the various versions of ReportServer. At the time of writing, the latest version is ReportServer 4.7. Download the latest version (the file should be named RS followed by the version number and the build number, followed by reportserver.zip). For example, RS4.7.2-6108-reportserver.zip denotes ReportServer version 4.7.2 build number 6108.

To obtain a trial version of ReportServer Enterprise Edition go to our download page and look for Binaries.

Download ReportServer (either enterprise or community). We will get back to this shortly.

Setting up ReportServer

Now that we have Tomcat and MariaDB set up, we can install and configure ReportServer. Let REPORTSERVER.zip denote the zip file that we downloaded in the very first step. Unzip the file.

Next, go to the Tomcat installation directory. If you haven't changed the directory during installation the directory should be

Here you should find a folder webapps that contains a single folder called ROOT. Remove the ROOT folder. Now move the extracted ReportServer folder into Tomcat's webapps directory and rename it to ROOT. Within the ROOT folder you should now have amongst others a folder called ddl and one called WEB-INF.

Next we create the ReportServer configuration directory. For this create the following directories

• C:\Program Files\reportserver
• C:\Program Files\reportserver\config
• C:\Program Files\reportserver\lib

The lib directory can hold additional jars (for example, additional JDBC drivers). The config directory can hold internal configuration files. For further information about the config dir see the chapter on the configuration dir in ReportServer's Configuration Guide.

In a next step we will copy default configuration files to the configuration directory. We will copy the following files to:

• C:\Program Files\reportserver\persistence.properties.example
• C:\Program Files\reportserver\reportserver.properties
• C:\Program Files\reportserver\logging-rs.properties

The files are located in the WEB-INF/classes directory. That is, if you installed Tomcat to its default location, the files are in

Copy the files to C:\Program Files\reportserver and rename the file persistence.properties.example into persistence.properties. This file holds the database configuration which we setup next. For this open the file persistence.properties with a text editor (if no proper editor is installed try Notepad++ which is freely available from https://notepad-plus-plus.org/) and set up the following connection parameters (replace the password with the password you chose during the MariaDB installation).

Setup Logging

By default, Tomcat will write its log entries into a file called catalina.out, which not only contains ReportServer specific entries but anything that involves Tomcat. To have a ReportServer specific log file, edit the file C:\Program Files\Apache Software Foundation\Tomcat 9.0\conf\logging.properties. Note that this step is optional and can be skipped in which case the standard Tomcat log structure will be used.

To have a ReportServer specific log file, the following changes need to be made to C:\Program Files\Apache Software Foundation\Tomcat 9.0\conf\logging.properties:

• add 5reportserver.org.apache.juli.FileHandler to handlers
• define handler specific properties
• tell tomcat to use the new handler for anything ReportServer specific
• adapt the log format to include a proper timestamp

A sample configuration could look as follows:

We are thrilled that you decided to give ReportServer a try. With this tutorial we want to give you a short introduction to our demo system and it should lead you step by step through the most important functionality from the perspective of end users.

First things first. You will find the demo system at

http://demo.raas.datenwerke.net

Or, if you already have ReportServer installed on your system, then you will probably find it at 127.0.0.1:8080/reportserver. In order to follow this tutorial you must have installed the demo data. If you have not done so already during the installation (try to log in with user: demodata, password: demodata to find out if the demo data is installed) follow these five steps:

1. Login with user: root, password: root (or the super user that you defined during installation)
2. Press CTRL+ALT+T to open the ReportServer terminal
3. Type "pkg install -d demob" (without quotes) and press TAB
4. The text should have been completed to look like:
   pkg install -d demobuilder-VERSION-DATE.zipIf so, press ENTER
5. Wait for a minute or so, once the terminal returns, reload your browser window.

In the following we will walk you through the demo system. If you would rather explore the demo system on your own initiative you can simply login with the following credentials:

username: demoadmin
password: demoadmin

This account will give you broad (although read-only) access to the system and allows you to explore almost all areas or ReportSever. Of course, if you have installed ReportServer locally then you can use the super user account that you specified during installation (default is: root/root) to get full access to ReportServer.

The Demo System

Our demo system simulates the reporting platform of a toys retailer. The data originates from the Eclipse BIRT Sample Database and was adapted by us to form a small data warehouse; that is, we mainly aggregated information according to different keys into aggregate tables. In addition we have created several reports which we will introduce in the following sections.

ReportServer comes with a very powerful and flexible permission system based on Access Control Lists. This flexibility can, however, also be a bit overwhelming and with this tutorial we want to provide a gentle introduction into working with permissions. This tutorial is meant as an addition to the description of permissions in the Administration Guide.

Groups and Roles

The Default Roles

Finally, let us quickly establish the permissions that are set for the two default roles in a fresh installation of ReportServer. The Administrators role is, again, granted access to any object. For this the permissions on each root folder in each tree are set. The Users role is granted permissions for the following generic targets:

• Users and Groups (read access to all objects; this allows users to for example choose others as schedule targets)
• Datasources (no access)
• Reports (read and execute access)
• File System (no access)
• Dadget Library (read access)

So much for the introduction to ReportServer's permission system. For further information see the Administration Guide.

In this tutorial we discuss how to set up a multi-tenant system in ReportServer.

ReportServer is built upon a very flexible permission scheme that allows to easily handle even the most complext requirements. For this tutorial we are going to consider the following scenario: A software vendor SV provides a set of services and wants to use ReportServer to allow its clients to access their data. We will demonstrate how to set everything up, so that the four clients A, B, C, and D get access. The data is structured such that every table in the datawarehouse is extended by an attribute CustomerID which specifies for which client the data record is.

The design goals of our setup are twofold:

1. Each client should get access to the system and to their data (and only their data).
2. We would like to reduce maintenance and administration overhead on the IT team of our software vendor SV as much as possible. In particular, reports should be generated only once and then be used for all clients. That is, the reports should not be duplicated for each client, but ReportServer should ensure that when client A is running a report that only the data for client A is included.

In order to set up the system we are going to use ReportServer's hierarchical model of users and ReportServer's user variable concept. In the following we discuss how to structure users in order to simulate separate sub systems for each client. We then discuss how to use user variables within reports to allow the reuse of reports across clients. Finally, we will discuss some more advanced use cases.

Adding Basic Reports

In the following we will create a report and provide access to the report to all clients. The report will be a Dynamic List on top of a database table called ClientData which has the following structure:

Reporting with User Variables

Our Demo Report was set up with the simple SQL query

Using parameters, we could, for example, add a dropdown box to the report which allows to select a client and then only show the data for that particular client. Assuming that we name the parameter P_CLIENT the adapted query could be:

Of course, adding a selection box to choose which client's data one wants to see does not solve the problem that in the current setup client A can see also the data of client B. The idea that we will use to restrict the access of each client will, however, use a similar approach. We will use a parameter to restrict the data records returned by the query, but we will not allow the user to select the parameter. Instead the parameter's value is automatically assigned depending on which user is currently logged in. The concept that makes this work are ReportServer's User Variables.

Careful with Permissions

In a multi-tenanted (and also in a single-tenant) setup one might be tempted to use TeamSpaces for granting or revoking access to reports. This is, however, not a secure approach. Permissions, that is, the right to access and execute a report is granted in the report management module. If a user is given the permission to access a report there, that user can access the report even in case he or she does not have access to any TeamSpace. All they would need to know is the report's id.

The default user role grants access to all reports in the system and is thus usually not well suited for a multi-tenant system where you often still have some reports which are specific to certain clients. It is thus adviseable to use a more granular permission scheme and, for example, have a report folder for each of the clients to store client specific reports. Permissions for these folders should then be granted only to users that belong to the corresponding client.

Similarly, the default user role grants read access to all users in the system, meaning, for example, that a user could select any other user in the system as a recipient of a scheduler job, or if a user is a TeamSpace manager he or she could add any other user to the TeamSpace.

Advanced Use Cases

After this short introduction there are two more advanced topics we would like to discuss. First we want to show the necessary steps to setup a user that sees the data for more than one client. For example, this could be an employee of our software vendor who is assigned to two clients and should also be able to see their data. The second point we want to briefly touch is how to use ReportServer scripts to perform some automated maintenance.

Automating ReportServer

In the final part of this tutorial we want to present a glimpse into what is possible using ReportServer scripts. What we would like to do is to automate the generation of TeamSpaces. That is, we want to create a script, that generates a TeamSpace for each client (unless the TeamSpace already exists) and synchronizes the users of that particular TeamSpace with all the users of the client. Of course, this could be extended by also checking reports which are in the TeamSpace etc. The possibilities are endless.

Following is the script. The explanation follows

In order to work with users, we will use the UserManagerService and for TeamSpaces we use the TeamSpaceService. Additionally, we need to import a few entity objects that we need to create (User, TeamSpaceMember and TeamSpaceRole). First we define the base OU, that is, the Clients folder in the user manager tree. We could load the OU by name but since that is not necessarily unique we opted to store its id. Then in lines 12 and 13 we load the two services that we are going to use in the script. To complete the script's setup we load the root user in line 16 and the actual OU object in line 19. Since each TeamSpace has an owner we need to assign this to some user and in the above script we will use the root user for this purpose.

The meat of the script starts in 22 when we loop over all children of the Clients folder. As each child represents a client we will create a TeamSpace for each of the children. The first step, in line 26 is to check whether the TeamSpace already exists. If this is not the case, we need to create it (lines 30 to 37). In the next step we remove all the members from the current team space (line 40). Finally, we loop over all the user objects beneath the current client folder and make them a member in the TeamSpace.

Admittedly, this was a rather quick explanation but we hope that this gives you some idea of what can be done with scripting. To get a better understanding of how scripting works, have a look at the scripting chapter in the administration guide as well as the ReportServer Scripting Guide.

This script could now be used by an administrator to update the current TeamSpace configuration, if users or clients changed, or it could even be scheduled and run on a regular basis, say once every morning.

This concludes this tutorial on multi tenant scenarios with ReportServer. As always we are happy about feedback.

Happy Reporting

ReportServer is available in numerous languages. However, if you like to add a new language, or improve one of the existing translations this document outlines the necessary steps.

Let’s start by looking at some of the core concepts of how different language versions of ReportServer are implemented. The first thing you need to know is that within ReportServer every text, label or message is assigned a unique key. You can view these keys by starting ReportServer using the special “keys”-language. To select this language append the locale=keys parameter to your ReportServer URL (e.g. http://127.0.0.1:8080/reportserver/ReportServer.html?locale=keys).

With ReportServer 3.0 Enterprise Edition we have added capabilities to style the user interface to allow to adapt the look and feel to match your corporate identity. In this tutorial we want to show how to develop a new theme and provide some helpers that make theme development easier.

The Configuration File theme.cf

The ReportServer theme is controlled via the configuration file /etc/ui/theme.cf which in its basic form looks something like:

The <theme> element has a single attribute type which controls the ReportServer base theme that is loaded. Currently two base themes are available which are called:

default

The standard ReportServer theme.

borders

The standard theme with some additional borders.

The <logo> tags allow to define the logos that are used for the login screen, the logo on the top left of the module bar as well as a logo to be used in the report documentation that is displayed in the TeamSpace. Let's consider the following directive:

Automatic Reload of Config File

When changing the configuration, the changes are only picked up, after we issue a config reload on the terminal. In the following we will write little script that will do this automatically. For this, we will listen to change events on files and if we detect a change on file theme.cf then we'll trigger a reload of the config file. Let's have a look at the script (for an introduction to scripting see the Administration and Script guides.

We are interested in change events on files (internally represented by net.datenwerke.rs.fileserver.­service.­fileserver.entities.FileServerFile objects). For this, we use the callbackRegistry in line 22 to attach an ObjectEventHandler for so called MergeEntityEvents (represented by class MergeEntityEvent.class).

ReportServer will throw events whenever an object is changed, and the above registration ensures that our script is called whenever an object of type FileServerFile is merged (i.e., changed). Now the callback itself implements the single method handle which takes one parameter, the event which should be of type MergeEntityEvent (as we only registered for these). Then in the remainder (lines 14 to 18) we simply check if the merged file is called theme.cf and if so we ask the ConfigService (loaded in line 8) to clear the cache for the theme config.

When registering to receive object events you need to ensure, that your code does not throw any exceptions, as these are executed within ReportServer's main thread and an error in this case would interrupt the storage of the changed file.

Now, if you execute the script then you will notice that after changing the configuration it is sufficient to reload the browser. The changes are then directly picked up and the new theme is loaded.

This already makes theme development a few clicks faster. In the next section we introduce one more helper, to make it a blast.

Reloading new Theme without Reloading Browser

Having to reload the browser is a bit tedious, so in this final part we are going to add a button to the toolbar on the theme.cf config file which instantly reloads the theme. Following is the completed script:

The script uses the ClientExtensionService (loaded in line 3) which allows to add buttons to various toolbars, or menus. In our case, we want to add a button to the toolbar in the FileServer when the theme.cf config file is active. For this we create an AddToolbarEntryExtension (lines 5 to 12) object which we give a label and an icon (choose any Font Awesome icon).

In line 8 we tell the extension that it should apply to the toolbar identified by fileserver:admin:view:toolbar (the file server's toolbar). Without any additional conditions, the button would now appear for every object in the toolbar. Thus, to only show it on file theme.cf we add a display condition and specify the specific path (lines 14-16).

The actual work (replacing the theme) is done when pressing the button and for this we use a little bit of javascript which we add to the entry in lines 10 and eleven. ReportServer's CSS is loaded into a link tag with the id rs-the-theme. So what we need is to remove it, and replace it with a fresh tag. For this we use jQuery. Removing the tag is done by

This is what we do in line 10, or almost. The reason why the above does not work directly is that ReportServer is written in GWT and the javascript is run within the GWT context (i.e., a nested frame). Thus, to access the actual context and its window object we use the variable $wnd which is provided by GWT for this purpose, making the call.

Now noticing that $ is a special instruction in groovy strings, we need to escape the $-signs.

In line 11 we add a fresh link tag to the head element which reloads the theme. And with this we are at the end of this tutorial.

Happy Theming

In this tutorial we introduce the scripting capabilities of ReportServer Enterprise Edition and look at four standard use cases for scripting: Script Reports, Script Datasources, Maintenance Scripts and Script Extensions. For a detailed introduction into scripting we refer to the ReportServer Scripting Guide. For this tutorial we assume a basic knowledge of programming, preferably in Java or Groovy.

Scripting 101

ReportServer comes with a scripting interface that allows you to run scripts written in the Groovy language in the context of ReportServer. ReportServer scripts are stored in the internal file server. In order to be executable they have to be placed somewhere beneath the bin folder. Usually, when working with scripts you will use the ReportServer terminal. You can open the terminal by pressing CTRL+ALT+T.

The ReportServer terminal mimicks a standard unix terminal. You can navigate to specific folders via the cd (change directory command) and show the contents of the current folder via the ls (list) command. Running the ls command on a freshly opened terminal should return the following output.

Scripting 101

ReportServer knows various virtual file systems for the various components present in ReportServer. That is, for users, reports, datasources, TeamSpaces and dashboards there exists a virtual file system that you can access via the terminal. In addition, the fileserver entry provides the root to the internal file system which we are going to use to store and run scripts.

To move to the root of the internal file server issue the following command.

The terminal supports auto completition. To try to autocomplete a command, press the TAB key.

If you again run the ls command you should now see the contents of the root folder of the internal file system (compare the output to the view provided in the administration module; they should be identical). Scripts need to be placed somewhere beneath the bin folder. If the folder does not yet exist, you can create it via

Note that, contrary to standard file systems ReportServer currently allows to have two (or more) identically named files (or folders) within the same folder. Hence mkdir bin will not throw an error message even if a folder with the name bin already exists. It is generally adviseable not to make use of this feature and we note that this might also change in future versions of ReportServer.

Let us create a directory called getstarted beneath the bin folder and move there.

In order to work with text files in the terminal there are two important commands that you should know: createTextFile takes a single argument and will create a new text file and open it for editing. editTextFile opens an existing file for editing. Again note that createTextFile, similarly to mkdir, does not check whether the file already exists, and allows you to create multiple files with the same name. Consider the following sequences of commands

By running the command createTextFile test.txt twice we have created two files with name test.txt. If you run the ls command with the -l flag, then you are given additional details, such as the ID of each element. In order to remove a file you can use the rm command. This command takes a single argument which points to the file you want to remove. This can be the name of the element in which case the first found element is removed. Alternatively you can remove an element via its id as

Thus, the following sequence of commands clears our getstarted directory again:

It is now time to create our very first script. Let us create the traditional hello world script.

Scripts by convention are given the suffix .groovy or .rs. Scripts can return a single object which if possible is printed to the console. Thus, to print the string Hello World onto the terminal we can issue a single return statement

Scripts can be executed directly from the terminal via the exec command. Sure enough, running exec hello.groovy writes Hello World onto the console.

Congratulations, you have just run your first ReportServer script. Before we dig deeper, let us discuss one of the most important aspects of scripting: debugging.

Error Handling

Let's be honest. Writing scripts that are flawless on the first attempt is almost impossible. Especially, once you are starting on a bit more complex scripts. Thus, being able to read error messages and find the bugs is one of the most important skills you will need to learn. A solid background in programming is, naturally, very helpful for this. However, don't be discouraged, even if you do not have a strong programming background. ReportServer tries to simplify error messages and point you towards the line that contains the error. If that fails, java stacktraces, though long and bulky at first, will become easier to read with time. And finally, the ReportServer community will help you, if you get stuck. So, to prepare you for this we start our scripting exploration with looking at how things go wrong. Before you try out the example, we suggest to read to the end of this section.

So how do error messages look like? Let us create a new script called error1.groovy (createTextFile error1.groovy) with the following contents (note that this script has a small bug):

Don't worry, if there is lots that you do not understand at this point. This script is, indeed, much more complex than our previous hello world script. In short, it uses the ReportService that is provided by ReportServer to access reports that are stored in the system. We use the service to get a list of all the reports in the system (getAllReports) and then for each of the reports we run the following Groovy closure:

A Groovy closure is a small code snippet that can be stored in a variable or passed as an argument to a function. A closure is wrapped in curly brackets, and consists of one or two parts. There can be an optional first part to define a (comma separated) list of parameters. In the above example this is

where we specify that there exists a single parameter which we name report. Then there is the (mandatory) closure body, in our case

Here we use the special object tout which is given to every ReportServer script and allows to write to the terminal via its println method.

So let's put this together. The script uses the ReportService to get all the reports in the system and then for each of the reports it executes the code provided by the closure which simply accesses the report's name and prints it to the console. Finally, since the script does not return anything we add a return null to the end of the script.

As mentioned earlier, the script contains a small bug, and if we execute it ReportServer will print the following error message.

Let us go through this line by line. The first line tells us, that the script execution failed. Ok, so this is what we expected. The next line contains the error message, and this often already pinpoints the problem. In this case the message says that there is no signature of method

Here everything until the last full stop identifies a class, and the final part a method. In short, the error message says that the (...)TableReport class (which represents a Dynamic List) does not have the method getname().

The error message then continues to give some information about the script that was executed, printing the arguments with which the script was called, a line number in which the error is suspected (line 6), and the line in question.

To rectify the error, we need to change report.getname() into report.getName(). With this change, the code the runs smoothly.

Now, at times the information provided by ReportServer does not allow to pinpoint the error. In this case it can be helpful to run the script with the -t flag which tells ReportServer to output the entire stack trace in case an error occurs. If we run our original error1.groovy script with the -t flag, we will get the following response:

That is quite a bit longer, than the standard error message. The first part, however, is identical, it contains the summary which we already saw earlier. Then, starting from line 13, we have the stack trace. The first line of the stack trace gives you the outer most error location which in our case is the location in ReportServer that calls the erroneous script: the GroovyEngine. This doesn't provide much information and similarly the following lines which provide information on the call stack that led to executing the script won't hold much information. The interesting bit starts with line 37 and the Caused by clause. With each Caused by we are getting one step closer to the original error position, so usually the last one is the one you should be looking for. We find the last Caused by in line 43 and it tells us that the error message originated in the call

From there we can trace the error backwards by looking at the following lines. We get our hit in line 50.

Anything that is prefixed Script refers to a dynamic groovy file, and since there is only a single file in our example, Script6 represents our script error1.groovy. The last number in each line represents the line number of the corresponding command, that is, line 50 of the stack trace tells us that the last line that was executed in our script was line 6.

This has been quite a lot of information, and don't worry if the stack trace still looks like a huge amount of nonsense. Usually, the summary message is sufficient to trace an error, and, with time, you will get used to reading stack traces.

Groovy with ReportServer 101

Now that we have an idea of how to deal with errors, let's have a look at the basic Groovy that you usually need when scripting. Being a fully matured programming language we can't hope to give you a complete picture. The good news is, there is tons of material on the net that tells you about how to get started with Groovy, and once you've mastered the basics, how to dig deep. A good start is the official Groovy website.

We have already seen the traditional Hello World program

Now, if you open the next best Groovy tutorial the hello world example will be slightly different. It will tell you that to print Hello World to the console you have to write

and they'd be right if you were using Groovy in a standard environment. Since we run Groovy within the context of ReportServer things are sometimes a bit different and this is one of these times. The println command tells groovy to print the following string to its standard output stream. Usually, that would be the console, for example, of your development environment. In ReportServer, the standard output stream of scripts is sent to the ReportServer log files and thus, if you execute the above script, although you will not see any message on the terminal window you will see the string Hello World if you expect the log files.

In order to write to the terminal in ReportServer you need to use the tout object which is short for (Terminal Output). Thus, if we translate the above to ReportServer we get

If we now execute this script (assuming it is called hello.groovy), we get the expected result:

Additionally to writing directly to the console, by convention ReportServer will print the result of the script (whatever the script returns) onto the console which is why

produces an equivalent result. One thing to note is that the return key word is not necessary. In other words, the script will return the result of the last instruction. So the following would again have an identical effect:

Now that we know how to print messages on to the terminal, let us introduce variables. Variables are defined via the def key word. The following code

prints I am a variable. Statements in Groovy can be terminated by a semicolon (as in the above example) but they don't have to. So equivalently we can write

Naturally, variables can hold not just strings but also, for example, numbers and we can work with variables.

The above code first defines a variable a to be the string "I am a String". It then changes a to 19, defines b as 23 and c as the sum of a and b. Also note the two ways of writing comments in Groovy via a double slash and slash-star. Strings as we have seen are enclosed in double quotes. Additionally, Groovy knows the following syntax for strings.

When using double quoted strings, you can also refer to other variables like so

Groovy has quite a few tricks when it comes to composing strings so you should definitely have a look at the templating capacitites that groovy has to offer (a good start is to search for "Groovy Templates").

Groovy supports the standard C/Java-like conditional and loop expressions.

You will probably often use lists and maps.

So be sure to check out the Groovy Collections as they have quite some nifty functionality. What we already saw in the error handling section was an example of how to iterate over a list of items via the each method of a list.

This prints each item of the list onto a single line. That is, the each method takes as argument a Groovy Closure which is executed for each of the lists items. For further information on the each method and other helper methods to use with lists see the Groovy doc for lists.

When you want to work with ReportServer or advanced Groovy objects you need to import them

Now that was some shorthand to write an HTML document the Groovy way with the MarkupBuilder object. The StringWriter object is part of the java.io package which is imported by default by Groovy and we could thus use it directly without additionally importing it. For more informatin on Groovy program structure and default imports look here.

So much for our little Groovy 101. As we mentioned at the beginning, this barely scratches the surface, but we hope that it helps to understand the remaining parts of this tutorial and that it encourages you to search the net for further information on Groovy. There is tons out there. And, if you get stuck, try our community forum or, if it is a programming question rather than a ReportServer question, have a look at stack overflow.

Installing Libraries

Before we look at what you can do with scripts in ReportServer let us briefly discuss how to install additional libraries for scripts that are not yet part of ReportServer. For example, if you want to access a REST webservice then you might want to use the Unirest library.

In order to install additional libraries they need to be placed on ReportServer's classpath. The easiest way to do so is to use the lib directory of the external configuration dir. In case you used the Bitnami installer this would be

If you did a manual installation and followed one of our tutorials for Linux or Windows then this would be

or

Once you've placed the .jar library files into the right location, you will need to restart ReportServer to make it aware of the new library.

Script Reports

The first use case we want to disucss are script reports. Script reports are the swiss army knife of reporting. They can be anything from a static list of data to a complex HTML5 application. The idea is that you use a ReportServer script to generate the output and hence, anything that you can program can be a report. So let us start with a simple Hello World example once more.

Hello Script Report

For a script report we need two ingredients, a script and a script report. Let us begin by preparing the script. We create a new script called helloreport.groovy with the following contents.

return """<html>
 <head>
  <title>A hello world</title>
 </head>
 <body>
  <h1>Hello Script Report</h1>
 </body>
</html>"""

What we have done is to simply return a static HTML page. While script reports can generate arbitrary outputs (e.g., PDFs, Excel or even custom byte formats) HTML is necessary when you want to present the result within ReportServer's report preview. Of course, just like other reports, a script report can also offer multiple output formats. We'll get to that in a moment.

Now that we have the script, the next step is to create the script report. For this we go to the Reports section in the administration and create a new Script report. What we need to configure for now is the name of the report (e.g., Hello Script Report) and we need to set the script to our previously created helloreport.groovy script. We can leave the other config options (datasource, arguments, export formats) blank for the moment.

Once we submit the report configuration and then open the report in ReportServer you should see a blank page with a single headline: Hello Script Report. Congratulations, you have just created your first script report.

Permissions. As with every other report in ReportServer script reports can only be executed by users that have the correct permissions. Note, however, that in case of a script report it is not sufficient to have the execute permission on the report object but that the user also needs the execute permission on the corresponding script.

Parameters

Naturally, script reports can make use of parameters. So let us add a a simple text parameter with key name to our script report. Now the question is, how can we access the parameter from within the script. To access parameters, ReportServer adds the special variable parameterMap to each script when it is executed via a script report. The parameterMap, as the name suggests is a map containing an entry for each of the parameters. Thus, to access our previously created parameter, we could use the following.

def name = parameterMap['name']
return """<html>
<head>
  <title>A hello world</title>
 </head>
 <body>
  <h1>Hello ${name}</h1>
 </body>
</html>"""

Datasources

If you look at the properties of a script report, you see that besides the script you can also provide a datasource. While scripts could leverage ReportServer's services to access datasources directly, providing a datasource as part of the configuration allows you to access the data more easily as ReportServer takes care of opening and closing a connection. Additionally, it would allow to reuse the same script with multiple datasources.

If you provide a database datasource as configuration (note that you do not need to provide a query), ReportServer will place a special connection variable into the scope of the script, that you can then use to load data from the datasource. Assuming we have configured our script with the demo datasource that is shipped with ReportServer. In this case, we could use the connection to read data using Groovy's SQL object as follows:

new SQL(connection).eachRow("SOME SQL SELECTION") { row ->
	/* do something with the data */
}

Following is a complete example (note that we need to import the SQL object). Additionally, we use Groovy's MarkupBuilder to get a somewhat more structured script.

import groovy.sql.Sql;
import groovy.xml.MarkupBuilder;

/* create writer for catpuring html output */
def writer = new StringWriter()

/* create report */
new MarkupBuilder(writer).html {
	head {
		title 'A script report with a data source'
	}
	body {
		h1 'Customer List'
		ul {
			/* get customer data from datasource */
			new Sql(connection).eachRow('SELECT CUS_CUSTOMERNAME FROM T_AGG_CUSTOMER ORDER BY 1') { row ->
				li row.CUS_CUSTOMERNAME
			}
		}
	}
}

return writer.toString();

Output Formats

So far we have only generated HTML reports. As mentioned before, script reports are of course not limited to producing HTML, although you would need to produce HTML if you want to show a preview within ReportServer. In order to add multiple output formats, you need to configure the Export formats property on the script report. Here you can provide a comma separated list of formats. For example, if you wanted to produce HTML and PDF output you could set the property to

HTML,PDF

If we adapt our previous script report with the above configuration and execute it, you will notice that now ReportServer offers you to export the report to HTML and PDF. However, whatever output format you choose, ReportServer will send you a text file with the HTML document. The reason is that we have not yet taken care of the different formats within our script.

In order to tell ReportServer what type of file it should provide as download, we need to return a special object of type net.datenwerke.rs.core.service.reportmanager.engine.CompiledReport (if you have downloaded ReportServer's API documentation search for CompiledReport). Further information on working with these CompiledReport objects can be found in the Scripting Guide. For the most common types (HTML and PDF) there is a shortcut which you can access via the special variable renderer.

Let us adapt our previous example, to produce PDF and HTML depending on the selected output format.

import groovy.sql.Sql;
import groovy.xml.MarkupBuilder;

/* create writer for catpuring html output */
def writer = new StringWriter()

/* create report */
new MarkupBuilder(writer).html {
	head {
		title 'A script report with a data source'
	}
	body {
		h1 'Customer List'
		ul {
			/* get customer data from datasource */
			new Sql(connection).eachRow('SELECT CUS_CUSTOMERNAME FROM T_AGG_CUSTOMER ORDER BY 1') { row ->
				li row.CUS_CUSTOMERNAME
			}
		}
	}
}

if(outputFormat  == 'pdf')
	return renderer.get("pdf").render(writer.toString())

return renderer.get("html").render(writer.toString())

The only parts that changed are the last three lines. The special variable outputFormat stores the output format specified by the user. In case of the preview in ReportServer the variable will contain the String preview. Otherwise it contains the format (in lowercase). In line 23 we check whether the output format specifies that we should produce a PDF report. To generate PDF, ReportServer offers a shortcut that allows to transform HTML directly into PDF. To get the PDF renderer and render html you use

renderer.get("pdf").render(StringContainingHTML)

The renderer transforms the HTML into a valid PDF document and creates the propert CompiledPDFReport object to let ReportServer know that the output is PDF.

Besides the PDF renderer there are also renderers for Microsoft Word (use renderer.get("docx")) and, of course, for HTML which we used in the very last line.

Script Datasources

While script reports provide you with a tool to implement almost any type of report requirement, script datasources allow you to incorporate almost any data source into the system to then use any of ReportServer's reporting engines (such as the Dynamic List) to report upon this data. In the following we are going to implement a datasource that accesses an XML dataset of the World Health Organization (WHO) to then use a Dynamic List to report upon it. The WHO offers various open datasets via http://www.who.int/gho/en/ and in the following we will show how to import a dataset on life expectancy per country which is available at

• WHO: Life expectancy by country

The dataset has the following format:

<Data xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://apps.who.int/gho/athena/data/GHO/WHOSIS_000001,WHOSIS_000002.xsd?format=xml&profile=simple-schema">
	<Fact>
		<COUNTRY>Angola</COUNTRY>
		<GHO>Life expectancy at birth (years)</GHO>
		<PUBLISHSTATE>Published</PUBLISHSTATE>
		<REGION>Africa</REGION>
		<SEX>Female</SEX>
		<YEAR>2015</YEAR>
		<Display>54.0</Display>
		<Numeric>54.02480</Numeric>
	</Fact>
	<Fact>
		<COUNTRY>United Arab Emirates</COUNTRY>
		<GHO>Life expectancy at birth (years)</GHO>
		<PUBLISHSTATE>Published</PUBLISHSTATE>
		<REGION>Eastern Mediterranean</REGION>
		<SEX>Both sexes</SEX>
		<YEAR>2015</YEAR>
		<Display>77.1</Display>
		<Numeric>77.06616</Numeric>
	</Fact>
	...
</Data>

In order to use this data set in ReportServer we need a script datasource that reads the above XML and transforms it into a format that ReportServer understands which in most cases will be an RSTableModel object. But, before we explain the details, let us show you the entire script.

import net.datenwerke.rs.base.service.reportengines.table.output.object.*;

/* the url from which to load the data */
def url = "http://apps.who.int/gho/athena/data/GHO/WHOSIS_000001,WHOSIS_000002.xml?profile=simple&filter=COUNTRY:*;YEAR:2015"

/* read in data */
def dataText = new URL(url).getText();

/* prepare table model */
def tableDefinition = new TableDefinition(
  ['Country', 'Region', 'Sex', 'Year', 'Life Expectancy'],
  [String.class, String.class, String.class, String.class, BigDecimal.class]
);
def model = new RSTableModel(tableDefinition);

/* process data */
def data = new XmlSlurper().parseText(dataText);
data.Fact.each { it ->
   model.addDataRow(it.COUNTRY.toString(),it.REGION.toString(),it.SEX.toString(),it.YEAR.toString(),it.Numeric.toBigDecimal())
}

return model;

22 lines, not bad. So let us go through this line by line. First line, we need to import the necessary objects to create the RSTableModel, which provides an internal object representation of a table for ReportServer. The whole point of the script, so to speak, is to then transform the XML structure into an RSTableModel.

In line 4, we simply store the URL with the data feed to then in line 7 read in the entire document to store it in variable dataText. Lines 10 to 14 prepare the RSTableModel object that we will use. To create an RSTableModel we need to tell ReportServer how the table will look like and we do this via a TableDefinition. The TableDefinition takes two lists, one to define the names of the table's columns and the second to define the data type of each column. In the example, we are going to transform the XML into the following table:

Here, the first four columns are of type String, the last column is a decimal number and hence of type BigDecimal.

Once we have a TableDefinition object, we can create an RSTableModel as done in line 14. What is left is to add the actual data to the model which we do in lines 17 to 20.

To process XML, Groovy offers a nice helper called the XMLSlurper. The first step is to read in our XML text into the XMLSlurper which happens in line 17. We can then use the resulting object to access various parts of the XML. For example,

data.Fact[0].COUNTRY

would access the COUNTRY field within the first Fact tag. Similarly, data.Fact contains a list of all the Fact tags and we use the each method to process each in turn (line 18). Line 19 now contains the transformation of a single Fact tag to a data row. We add a new data row to our RSTableModel via the addDataRow method and provide the data fields as input. Here we need to ensure that the fields are of the appropriate type and we use the toType helper methods provided by the XMLSlurper.

And, that is it. You can now use this script to power a script datasource which can then be used, for example, together with a Dynamic List. To create a script datasource go to the Datasources section in the Administration module and create a new Script Datasource which you configure with the script.

Behind the Scenes

When working with script datasources it is important to understand what happens behind the scenes. If your script returns an RSTableModel, ReportServer will load the resulting data into its Internal Database, that is, into a temporary database table. This allows all the reporting engines to access the data as they would access any other database tables and thus all the functionality of the Dynamic List or Jasper can be used when reporting on a scripted data set.

Loading data from an external source, processing it, and then loading it into a database takes some time which is why you might not want to perform these steps for every single request that is made to the data set. For this, ReportServer allows you to define whether or not a data set defined via a script datasource is cached and if you decide to enable a cache for how long the data is cached before it is recomputed. By default the Database cache option of a script datasource is set to -1 which means that the data is cached indefinitely. To turn off the cache, set this entry to 0. Any positive integer specifies a cache in minutes, for example, a setting of 10 would mean that the data is recomputed after 10 minutes (but only if it is accessed).

In case you want to clean the cache manually, you can simply hit the Apply button on the script datasource. That is, any change on the script datasource (and even if no property actually changed) will cause the cache to be flushed.

Maintenance Scripts

A very useful property of scripts is that they can access the entire ReportServer object model and thus can be used to automate and maintain the platform. For example, you can automatically generate users, or reports, synchronize user groups with TeamSpaces or automatically update user dashboards. Or consider the case that some fields changed in your data warehouse and you now want to understand the impact this is having on existing reports. You could, for example, search for all Dynamic Lists that contain a particular attribute, or even perform a test execution of all reports in the system.

In order to make use of these techniques you will need a basic understanding of the ReportServer object model and the helper services provided by ReportServer which goes far beyond this tutorial. A good place to start is the scripting guide as well as the various blog posts and tutorials. Also, you might want to have a look at the API documentation and ReportServer sources. For questions and pointers also try our community forum or if your company has a support contract, our development team will be happy to help.

In the introduction we have already seen an example of how to use ReportServer service objects to loop over all the reports in the system. For this we used the ReportService object provided by ReportServer. The most important services to manipulate objects are:

Each service manages a set of related entities, for example, the ReportService is used to fetch or create report entities. But there is not only one entity to represent a report, but one entity per report type. For example, Dynamic Lists are internally represented by net.datenwerke.rs.base.service.reportengines.table.entities.TableReport while a BIRT report would be represented by objects of type net.datenwerke.rs.birt.service.reportengine.entities.BirtReport. All together, ReportServer consists of more than 180 different entity objects.

To get a list of all provided services and entities in ReportServer, download the API documentation.

When starting to manipulate ReportServer's object model with scripts you can seriously damage your installation. You should thus develop scripts always on a seperate development server and only deploy such scripts that have been thoroughly tested.

To access ReportServer internals we have said that you will need to access ReportServer's services. For this, ReportServer provides yet another special variable to every script which is called GLOBALS and which offers various helper methods. In particular, it offers the method getInstance which allows you to obtain a ReportServer service. To load a ReportServer service you will need to import the service class and then use GLOBALS.getInstance to access the service. The following example loads the UserManagerService.

import net.datenwerke.security.service.usermanager.UserManagerService;

def userService = GLOBALS.getInstance(UserManagerService.class);

We could now, for example, use the service to list all users in the system.

import net.datenwerke.security.service.usermanager.UserManagerService;

def userService = GLOBALS.getInstance(UserManagerService.class);

userService.getAllUsers().each{ it -> tout.println it.getFirstname() + " " + it.getLastname() }

return null;

So what about creating a new user? The user entity is net.datenwerke.security.service.usermanager.entities.User and we can create a new user object by

import net.datenwerke.security.service.usermanager.entities.User;

def user = new User();
user.setUsername("testuser");
user.setFirstname("John");
user.setLastname("Testuser");

This script alone, however, does not add a user to the system. For this, we would need to make ReportServer aware of the user and attach the user into an organizational unit (i.e., add it as a child of a user folder in the user tree). For the first part we need to call the persist method of the UserManagerService and pass the newly created user. To add the user to a folder, we need to load a folder that is already in the system. To obtain the root folder of the user tree we can use the method getRoots() of the UserManagementService. Note that the method is called getRoots and not getRoot and indeed it returns a list rather than a single object. This is due to the fact that the abstract implementation of a tree in ReportServer can have multiple roots. In case of the user tree, there will, however, always be only one root object so we can access the folder via getRoots().get(0). Once we have the folder, we can add the user by calling the addChild object of the folder.

Note that all tree-based entities, i.e., any entity that is represented in a tree in ReportServer such as users or reports have a method called setParent. It may be tempting to add a user to a folder by calling user.setParent(folder). Don't!

Thus, we have all that we need to put the example together. Following is the resulting code.

import net.datenwerke.security.service.usermanager.UserManagerService;
import net.datenwerke.security.service.usermanager.entities.User;

/* load service */
def userService = GLOBALS.getInstance(UserManagerService.class);

/* create user */
def user = new User();
user.setUsername("testuser");
user.setFirstname("John");
user.setLastname("Testuser");

/* load root folder and add user */
def root = userService.getRoots().get(0);
root.addChild(user);

/* persist user */
userService.persist(user);

return "added new user";

If you run the above script on the terminal you will see that it returns with the message added new user, but if you go to the user management and look the user isn't there. The reason for this is that, by default, scripts are executed in non-commiting mode meaning that changes to ReportServer's object model will not be made persistent. This provides an extra level of security to not accidentally cripple your system by running the wrong script. In order to run a script in commiting mode you need to call exec with the -c flag. Thus, if your script is named addUser.groovy then you need to call:

exec -c addUser.groovy

Now, if you refresh the user tree you should see John Testuser beneath the root OU. We'll leave you to explore the possibilities at this point. And once more let us warn you: ReportServer scripts are a fantastic maintenance tool. However, remember that with great power comes great responsibility, so please make sure to develop and test your scripts on a dedicated development machine.

Script Enhancements

The final use case that we want to discuss in this tutorial is the enhancement of ReportServer using scripts. ReportServer is build upon a flexible Hooking mechanism which allows to register hooks that can add or influence various functionality. For example, you can register a hook that is called before a report is executed to either change or deny execution. A list of all available hooks is given in the API documentation. Besides registering hooks, you can also register for certain events, such as the event that an entity changed or was removed. You could then either perform an action or deny the change by throwing an exception.

As an example we are going to implement the net.datenwerke.rs.core.service.reportmanager.hooks.ReportExecutionNotificationHook which is called before a report is executed. Hooks that were designed to be implemented by scripts usually come with a default implementation called HOOKNAMEAdapter. In the case of ReportExecutionNotificationHook we should thus find the ReportExecutionNotificationHookAdapter. You should always implement the adapter rather than the hook directly. To implement a hook in Groovy we create a map that for each of the methods we want to implement has a closure. In the example, we want to implement the doVetoReportExecution method and deny execution after seven pm. We understand that reporting is fun, but at some point we should call it a day. To implement the hook we use the following structure

import HOOK_NAME;
import HOOK_NAME_ADAPTER;

def callback = [
	method1 : { params ->
	},
	method2 : { params ->
	}
] as HOOK_NAME_ADAPTER;

If you are familiar with Java, then what we are doing is that we provide an anonymous implementation of the hook. Using a map and the as class keyword is a Groovy shortcut for implementing interfaces.

Note that we import both the actual hook and the adapter. We will see in a moment why. So here is the implemataton of ReportExecutionNotificationHook.

import net.datenwerke.rs.core.service.reportmanager.hooks.ReportExecutionNotificationHook;
import net.datenwerke.rs.core.service.reportmanager.hooks.adapter.ReportExecutionNotificationHookAdapter;

def callback = [
	doVetoReportExecution : { report, parameterSet, user, outputFormat, configs ->
		if(Calendar.getInstance().get(Calendar.HOUR_OF_DAY) > 19)
			throw new RuntimeException("Have some free time.");
	}
] as ReportExecutionNotificationHookAdapter;

All that is missing now, is to make ReportServer aware of the hook. That is, to hook-in our implementation. For this, we once more use the GLOBALS object which provides a service called callbackRegisry which manages the hooking in for us. Here we finally need the actual hook class (and not the adapter) to tell the service where to hook this in. Following is the completed example.

import net.datenwerke.rs.core.service.reportmanager.hooks.ReportExecutionNotificationHook;
import net.datenwerke.rs.core.service.reportmanager.hooks.adapter.ReportExecutionNotificationHookAdapter;

def callback = [
	doVetoReportExecution : { report, parameterSet, user, outputFormat, configs ->
		if(Calendar.getInstance().get(Calendar.HOUR_OF_DAY) > 19)
			throw new RuntimeException("Have some free time.");
	}
] as ReportExecutionNotificationHookAdapter;

GLOBALS.services.callbackRegistry.attachHook("NO_WORK_AFTER_SEVEN", ReportExecutionNotificationHook.class, callback)

Note that we've provided a name for our implementation: NO_WORK_AFTER_SEVEN. This is used, such that if we execute the script twice (for example, if we want to change something in the implemenation), the hook is replaced rather than that a second one is added. It also allows us to deregister the hook at a later time via the detachHook method of the callbackRegistry.

Once you've executed the above script, report executions after seven are not longer possible and this is also where we end this tutorial. We hope that this provided some first insights into scripting. Scripting is one of the most complex but also one of the most powerful tools in ReportServer. Furthermore, scripting can be fun, not the least because it allows you to get the job done, whatever it is.

If you have any feedback to this tutorial, we are always happy to hear about it. Until then.

Happy Scripting.

In this tutorial we describe how to set up a development environment based on Eclipse to look into ReportServer 3.0 Community Edition as well as to have an ideal environment for developing ReportServer scripts. With ReportServer 3.0 we have significantly simplified the process of setting up a development environment. Nevertheless there are quite a few steps that we need to follow. In short these are:

1. Download a recent version of Eclipse
2. Download GWT 2.7
3. Configure Eclipse to use GWT
4. Download ReportServer
5. Download additional libraries
6. Setup the project in Eclipse
7. Start ReportServer from within Eclipse

In the following we'll go through these step by step.

Download GWT

ReportServer is build on top of GWT (http://www.gwtproject.org/). To set up GWT we will need to download the GWT SDK 2.7 as well as set up the GWT developer tools in Eclipse. First step is to download the GWT SDK which is available from the GWT download page. Make sure to get version 2.7 (the latest stable version at the time of writing). If a newer version appears you will find the older versions in the GWT download archive.

Once downloaded, unpack the archive and put the folder gwt-2.7.0 somewhere safe. We'll need it shortly when setting up GWT in Eclipse.

Download ReportServer

Next, we need to download the ReportServer 3.0.1 sources as well as binaries. (The latter will be used to get most of the necessary libraries.) Sources and binaries are available from sourceforge.

Once downloaded, unpack both archives. The sources should contain a single folder ReportServer which in turn contains three folders: metamodel, src and war.

Download Additional Libraries

Besides the ReportServer sources and binaries we need some additional libraries to successfully compile ReportServer. These are

• Juel (Version 2.2.7)
• SLF4J (to get decent logs)
• rs-entityservices.jar
• rs-saiku.jar
• rs-mockup.jar

You can get Juel from http://juel.sourceforge.net/. We'll be using the juel-api-2.2.7.jar that comes with Juel.

SLF4J is a logging framework and we will be using the slf4j-simple logger to set up a basic logging. You can download slf4j from http://www.slf4j.org/download.html. Look for version 1.7.12 (although the latest version will probably work as well).

As for the three remaining jars, you can download them directly via the above links.

Hit Finish to create the project. You should now have a more or less empty project that has a src folder with the single empty package net.datenwerke as well as a war folder containing WEB-INF/lib/gwt-servlet.jar and WEB-INF/web.xml.

Copy Libraries: In the following we are going to copy the necessary libraries to WEB-INF/lib. First copy the perviously downloaded additional libraries:

• juel-api-2.2.7.jar
• slf4j-simple-1.7.12.jar
• rs-entityservices.jar
• rs-saiku.jar
• rs-mockup.jar

Next, we are going to copy most of the libraries from the ReportServer binaries over. In the unpacked ReportServer binaries that you downloaded earlier you will also find a WEB-INF/lib folder. Copy all the jars from that folder to the new project WEB-INF/lib folder except for the following jars:

• gwt-servlet-2.7.0.jar
• reportserver.jar
• rs-schemaupdate.jar
• slf4j-ext-1.7.12.jar

Copy war: Next we are going to copy the relevant files from the ReportServer sources' war directory. In the ReportServer sources' war directory you will also find a WEB-INF directory containing two xml files web.xml and sun-jaxws.xml. Copy both files to the project's WEB-INF directory thereby overwriting the web.xml file that is already present. Directly beneath the war directory in the unpacked sources you should find additional files and folders (favicon.ico, licenses, ReportServer.html and resources). Copy these to the package's war directory.

Starting ReportServer

In order to start ReportServer we first need to prepare a database and configure the connection settings. Installing a database is out of the scope of this tutorial so we have to assume that you already have one of the supported database systems running. In the unpacked binaries archive you will find a folder called ddl which contains SQL scripts to set up the necessary structures. Choose the script for your database and execute it.

Further information on the database setup is also given in the ReportServer Configuration Guide.

Now that we have a database ready, we need to tell ReportServer how to access it. For this we'll copy a sample configuration file from the binaries archive over to the project folder. The sample configuration is called persistence.properties.example and can be found in WEB-INF/classes in the binaries archive. Copy the file into the src folder within your Eclipse project. That is, it should be next to the other config files such as reportserver.properties.