Introduction
The Report Server can only be installed on one machine using the installation routine supplied. However, if a distinction is to be made between different scenarios, e.g. for development purposes, quality assurance or productive systems, this would already require three installations on three different machines. Of course, this can be easily implemented today with the help of virtualized capacities. But even a virtualized network with multiple machines requires licenses for the operating system, any SQL server instances, etc. But also the deployment for different customers, so that they do not technically get in each other’s way, would require an independent machine per customer.
To enable such independent scenarios to be implemented with the Report Server on one and the same machine, the technical basis for so-called multi tenacy was created in the Report Server. In order to ensure a maximum degree of isolation from one another, both the database for the administration of the Report Server itself and access to the respective website of the Report Server are completely separated from one another in the approach described here.
Requirements and Initial Situation
To enable the Report Server to run multiple times on one and the same machine, technical adjustments were necessary, so that at least version 26.004 must be used for this. Since a multiple installation is not intended, an already existing installation of the Report Server, which is completely set up and configured, is therefore assumed as a basis. Please also make sure that the Report Server installation, which is used as a template for further clients, has previously been called externally from another machine/client in order to complete the task service setup for the planned reports. It is recommended to perform a full system backup beforehand.
Create an Additional Tenant: Required Steps
The steps necessary to create additional independent tenants of an existing Report Server installation are described below. Please make sure that you have administrator rights on the system in question and that you also have access to the Report Server database system. In the case of Microsoft SQL Server, for example, via the Microsoft SQL Server Management Studio or for PostgreSQL via pgAdmin.
Important Directories and Files
In order to be able to run the tenants independently later and to make individual settings such as the underlying database, it is necessary to copy the existing directory structure. This includes on the one hand the installation directory and on the other hand the so-called cache directory.
Installation Directory
In a standard installation of the Report Server, this directory is usually located under C:\Program Files\combit\combit Report Server\ and contains all the files needed to run the Report Server. Now copy the whole directory including all subdirectories to an individual name like C:\Program Files\combit\combit Report Server QA\. Special administrator permissions may be required for this.
Cache Directory
This directory is used by the Report Server to manage temporary files, cached reports, etc. and is created as part of the default installation at C:\ProgramData\combit\combit Report Server Cache. If the directory cannot be located at first attempt, the information can also be found in the privateSettings.config file in the WebUI directory of the installation directory:
…
<setting key="CacheDir">C:\ProgramData\combit\combit Report Server Cache</setting>
…
Now copy the entire directory including all subdirectories to an individual name such as C:\ProgramData\combit\combit Report Server Cache QA\. Special administrator permissions may be required for this.
IIS Configuration and Permissions
Start the Internet Information Services (IIS) Manager in order to configure the application pool (AppPool) and the associated permissions as well as the application/web site for the new client.
Application Pool/AppPool
Unfortunately, a copy function is not available in the IIS Manager for this purpose, so a new AppPool must be created manually. Assign a meaningful name for the new AppPool so that it can be easily associated with the corresponding client, e.g. combitReportServerQA.
Important: For the .NET CLR version setting, please be sure to use the No Managed Code option and set the managed pipeline mode to Integrated.
Create new Application/Web Site
Now create a new application via the right-click context menu using the Add Application item in the Sites/Default Web-Site area and define the following basic settings for it:
Alias: combitReportServerQA
Application pool: combitReportServerQA
Pyhsical path: C:\Program Files\combit\combit Report Server QA\WebUI
Permissions
In order for the new report server tenant combitReportServerQA to be able to perform its services, special permissions must now be defined for various paths. The special feature here is that no Windows user is entered as authorization, but the newly created AppPool combitReportServerQA. The following steps must therefore be performed once for the new WebUI installation directory (C:\Program Files\combit\combit Report Server QA\WebUI) and the new cache directory (C:\ProgramData\combit\combit Report Server Cache QA) as well as the directory for the Task Service (C:\Program Files\combit\combit Report Server QA\TaskService).
Edit the appropriate directory permissions using the Windows Explorer Security tab. Add a new user by typing the following name and clicking Check Names: IIS Apppool\combitReportServerQA.
The dialog will then automatically change to the name combitReportServerQA. Now grant this user full access to the selected directory and its subdirectories.
Scheduled Reports (1): Create and Prepare Task Service
In order that scheduled reports can be executed independently in the respective tenant, corresponding system adjustments are necessary.
Create Windows Service
Start a Windows command prompt - which must be executed with administrator privileges! - to create a new service for the new Task Service of the new Report Server tenant combitReportServerQA. For this purpose, the following command must be executed:
sc.exe create "<NAME>" start=delayed-auto binPath="<PATH>"
Where NAME can be freely chosen here; however, under Windows it must be a unique name. For the new mandate, we choose the name combit Report Server QA Task Service.
PATH must point to the application for the Task Service of the new tenant in its installation directory:
C:\Program Files\combit\combit Report Server QA\TaskService\combit.ReportServer.TaskServiceWorker.exe .
Thus, a sample command for the command prompt would read as follows:
sc.exe create "combit Report Server QA Task Service" start=delayed-auto binPath="C:\Program Files\combit\combit Report Server QA\TaskService\combit.ReportServer.TaskServiceWorker.exe"
If the command is processed successfully, this is confirmed with a [SC] CreateService SUCCESS.
The service itself should not be started yet, because the final settings are not fixed at this time. This will be done in a later step.
Database
The Report Server uses its own database for its own administration and settings, which can be used either under Microsoft SQL or PostgreSQL. This is where the report templates, data source configurations, user administration, general settings, etc. are stored. To create this administration database of the Report Server, there are two variants, depending on the requirements:
-
To ensure that the existing data structure is now available for the additional tenant and meets the technical requirements, a complete copy should be made as part of a database backup. Based on a Microsoft SQL database and the Microsoft SQL Management Studio, this would be the following steps. Deviations in the individual points for different versions of Microsoft SQL Server and Microsoft SQL Management Studio cannot be ruled out. For this purpose, follow the steps in Using an existing Database as a Data Source Layer.
-
If you want to create a completely empty management database for the new tenant, you can use the integrated setup wizard of the Report Server. Follow the instructions in Create a new/empty Database as a initial Data Source Layer.
Using an existing Database as a Data Source
The following procedure describes the necessary steps using SQL Server Management Studio.
Create Backup of existing Database
If you do not want to make a standalone file backup of the database, you can also skip this point in order to perform a direct restore of the database later on without an intermediate file backup. Find the existing Report Server database with the name combitReportServer and open the backup wizard for it. This can usually be reached via the context menu Tasks > Back Up. Make absolutely sure that Full is always selected as the backup type and specify an appropriate file path and name.
Create new Database with new Name
Now, a new database must be created, for which the context menu is also used. Select the item New Database… under Databases to start the wizard for creating a new database. Now enter a corresponding new database name, such as combitReportServerQA. Normally, all other settings can be left as they are. In addition, however, a comparison of the settings between the existing outgoing database combitReportServer and the new database combitReportServerQA can be performed.
Restore Backup to new Database
Finally, the previous backup/copy must now be restored to the newly created combitReportServerQA database. To do this, open the Restore Wizard using the context menu Tasks > Restore > Database…. Select the existing outgoing database combitReportServer as the source and make sure that the destination database name is still combitReportServerQA. A previous full file backup of the outgoing combit Report Server database can also be specified as the source. It is now important that WITH REPLACE (Overwrite the existing database) is activated in the options for the restore.
Database Customization for the Task Service (Scheduled Reports)
In the newly created combitReportServerQA database, the value for the name TaskHelper.EventName in the CmbtSettings table must be updated so that a different or new GUID is used. This is the only way that the planned reports can be executed accurately and independently in the later course and execution of the different clients. The structure of the value must look as follows: Global\{CMBTRS:<GUID>}
An example could therefore be:
Global\{CMBTRS:CCF8473D-A860-432C-8C50-AF252FF40965}
Customize privateSettings.config
This is the central control file for the Report Server application, it contains information about the used database and other important information and is located in the WebUI subdirectory. This must now be adapted accordingly for the created copy C:\Program Files\combit\combit Report Server QA\WebUI\privateSettings.config, so that the new database, directories etc. are used. To do this, open the file with a text editor and note that you need administrator permissions to save the changes in the file.
…
<setting key="CacheDir">C:\ProgramData\combit\combit Report Server Cache QA</setting>
<setting key="CoreDbConnection">Data Source=<MYSQLSERVERINSTANCENAME>;User ID=cmbtreportserver_user;Password=<MYPASSWORD>;Initial Catalog=combitReportServerQA</setting>
<setting key="InstanceIdentifier">combitReportServerQA</setting>
<setting key="CoreDbProvider">combit.ReportServer.DataLayer.SqlClientDatabase</setting>
…
Note for the Setup under PostgreSQL
When using PostgreSQL, the two values for CoreDbConnection and CoreDbProvider must have the following schema:
…
<setting key="CoreDbConnection">Server=<MYSERVER>;Port=<MYPORT>;Database=combitReportServerQA;User Id=cmbtreportserver_user;Password=<MYPASSWORD>;</setting>
<setting key="CoreDbProvider">combit.ReportServer.DataLayer.PostgreSQLDatabase</setting>
…
Create a new/empty Database as a initial Data Source Layer
If no existing Report Server database with its reports, data sources, etc. is to be used for the new tenant, a completely empty database can be set up by the setup wizard. However, some points have to be considered in advance so that the setup wizard can be executed successfully.
Customize privateSettings.config
In the central control file for the Report Server application of the new client, which is located in the WebUI subdirectory (C:\Program Files\combit Report Server QA\WebUI\privateSettings.config), the following changes must now be made. To do this, open the file with a text editor and please note that you need administrator permissions to save the changes in the file.
…
<setting key="IsDbReady">false</setting>
<setting key="CacheDir">C:\ProgramData\combit\combit Report Server Cache QA</setting>
<setting key="InstanceIdentifier">combitReportServerQA</setting>
…
Start Setup Wizard
As changes have been made in the privateSettings.config file, the newly created AppPool combitReportServerQA must now be restarted in the Internet Information Services (IIS) Manager. Now the current state of the new tenant can be started in the browser via the address http://localhost/combitReportServerQA, which will automatically start the setup wizard. Here, enter the desired database name - in our example combitReportServerQA - in the wizard and follow the further steps - but only until the prerequisites are checked. Now, first follow the instructions in Scheduled Reports (2): Configure and Start Task Service (see below) before you continue in the setup wizard, so that only then the prerequisites can be finally checked and the setup wizard can be successfully completed.
Scheduled Reports (2): Configure and Start Task Service
In order for the new Task Service to work with the settings of the new database, the appropriate settings must be communicated to it.
Copy privateSettings.config
The current state of the privateSettings.config file from the WebUI directory of the new tenant (C:\Program Files\combit\combit Report Server QA\WebUI\privateSettings.config) must now be copied to the directory of the Task Service of the new mandate under C:\Program Files\combit\combit Report Server QA\TaskService.
Start Service
Now start the new created service with the following command in a Windows command prompt executed with administrator privileges:
sc.exe start "combit Report Server QA Task Service"
You can determine whether the service was started successfully with the following command:
sc.exe query "combit Report Server QA Task Service"
Starting the new Tenant
Now it is time for the new tenant to be executed and started. To do this, the previously newly created AppPool combitReportServerQA must be started in the Internet Information Services (IIS) Manager. Now the configuration of the new client combitReportServerQA is complete and it can be started via the browser on the server with the address http://localhost/combitReportServerQA.
Note: The first start of the application via the browser may take a little longer until all runtime modules etc. are loaded. You may be prompted in the dashboard of the new mandate to check the default printer or to reset it to the Microsoft XPS Document Writer.
Service Pack- or Patch-Installations
Since each Report Server mandate now has its own database, directories, etc., to ensure maximum independence, both the regular service pack installation and the Manual Patch Installation are a bit more involved in this scenario. Once the original mandate has been updated, the files must be manually transferred from its installation folder (by default, this is usually C:\Program Files\combit Report Server) to the other clients accordingly.
Attention: Before replacing the files manually in the tenant’s directories, it is absolutely necessary to save the privateSettings.config file first - both for the WebUI directory and the TaskService directory. This file should be restored after the copying process is finished, because it contains the important data of the client like directories, database, etc.
Future Prospects and Further Work
If individual reports, data sources, etc. of a Report Server tenant are to be transferred to another tenant, the import/export function can be conveniently used for this purpose. A short description can be found in the online documentation in chapter Import/Export.