Central Reports

Central Reports
Prev	Chapter 10. Multi-Server and Multi-Site Deployments	Next

Overview

Organizations with multiple sites will typically follow one of two deployment strategies: centralized or decentralized. This includes businesses with offices in multiple cities and education institutes with international campuses. Each model comes with its own pros and cons.

One advantage of the decentralized model is that a system administrator at one site can't inadvertently make changes that affect the other sites. Poor inter-site link reliability and simplified site administration are other motivators for adopting the decentralized model. The main disadvantage of decentralization is the difficulty of gaining a unified view of print data and reporting. Central Reports solves this problem.

This chapter covers how Central Reports provides you with a consolidated data and reporting view across multiple primary/application servers (decentralized model). If you are using a single application server (centralized model) this is not required as the regular reports provide the data you need - see Chapter 9, Reports.

A typical scenario is an organization with multiple sites and one application server per site. With Central Reports organizations like this can access consolidated reports for the entire organization.

Figure 10.5. Central Reports across multiple application servers

Central Reports works by running the same SQL query on all remote PaperCut databases and consolidating the result. This is done by first concatenating the result data from all databases, then grouping, sorting and aggregating as appropriate. For this purpose, entities such as users, groups, printers and accounts are matched by name. For example, if print usage records matching username "Mary" are received from multiple sites, they are all considered as coming from the same user and are aggregated. In other words, users (and some other entities) are considered to be unique across all sites.

We've taken most reports that are suitable for aggregation across systems and made them available in Central Reports. This includes the Executive Summary report and most usage reports. Not included are configuration reports, transaction reports and print log reports.

Central Reports may be scheduled for automatic generation and email distribution just like standard reports and we anticipate that most customers will want to use Central Reports in this way.

Tip

Central Reports is not a centralized management system. Your multiple PaperCut application servers must continue to be operated and managed independently. All configuration and balances remain local to each application server, including user and shared account configuration, admin rights and user balances.

Prerequisites for Central Reports

Your organization needs at least two production application servers to use Central Reports. You can configure Central Reports on one or both of these application servers. You can also configure Central Reports on a separate PaperCut installation used solely for the Central Reports feature.

In addition:

Each PaperCut application server (including the reporting server) must be configured with an external database (see the section called “Overview” in the external database chapter). This database must be accessible for read access from the central server by a nominated URL, user and password.
Central Reports works by running SQL queries on the remote PaperCut databases directly. It is therefore possible as an alternative approach to use other mechanisms to replicate the remote databases to your reporting server and run reports from the local read-only replicas. In this manual, however, we will document only the usual approach of accessing remote databases directly.
All databases must be of the same type. For example, if you use Microsoft SQL Server at one site, this database type must be used at all sites, including the site doing the reporting.
You should ensure the same PaperCut version is installed at each location, including the central reporting location. More specifically, the databases at all sites must use the same database schema (which can change between PaperCut versions).
By default, Central Reports will not generate reports if any remote databases are unavailable or return errors. It is often better to log these events as errors rather than generate potentially incomplete and misleading reports. Central Reports has a Status page which gives you a quick snapshot of the readiness of the system and flags any errors.
If desired, you may instruct central reports to generate reports even if some remote databases are unavailable. To configure, see the section called “Server Configuration”.

Setting up Central Reports

Before setting up Central Reports, please review the prerequisites in the previous section. If you have not yet set up your external databases at each site, including the reporting site, you must do this first by following the instructions in the section called “Upsizing to an External RDBMS”.

Select a server as your reporting server. This is the server at which you will configure and run Central Reports. You may choose whichever server is most convenient for you. In fact, it is possible to configure several or all servers to be able to run Central Reports.
On the server, open the server config file [app-path]/server/server.properties in a text editor (e.g. Notepad).
At the bottom of the file, add central-reports configuration statements as documented in the section called “Server Configuration” below and save the file
Log into the PaperCut admin interface to configure admin rights and email notifications:
To grant Central Reports admin rights to users who need access:
1. Navigate to the Options → Admin Rights page.
2. Select the group you wish to add Central Reports rights for and click Add Group. Or if adding a single user, enter the user and click Add User.
3. By default the group or user you added will have access to all features. To change this, click on the edit link to the right of the group or user entry. You may then select the specific rights you wish to apply. In particular, ensure that Access Central Reports is checked and click Apply to save your changes.
Enabling an email (SMTP) server allows scheduled Central Reports to be sent. Additionally, enabling email error notifications is recommended so that administrators are notified of any issues that would prevent Central Reports from running successfully). E.g. if a scheduled central report fails, this allows administrators to be notified by email rather than needing to log into the admin interface and check the App. Log tab. To enable email notifications, navigate to Options → Notifications and:
1. Under Email Options, enter an SMTP server and other details so that PaperCut can send emails.
2. Recommended: under System Notifications, enable Notify on error level events.
Log into the Central Reports interface using the URL https://[server-name]:9192/central-reports and check the Status page for any errors. If this page is not available, please check that you have added Central Reports admin rights to your login.
Select the Central Reports tab and run several reports to test. Verify that the reports run and that the results are as expected.

Server Configuration

Central Reports is enabled by configuration statements in [app-path]/server/server.properties. Changes to the Central Reports related settings in this file do not require a restart of the PaperCut application server (although most other settings in this file do).

This file should include template examples for configuring Central Reports. If it does not then you can see the [app-path]/server/server.properties.template (which is kept up to date with every upgrade) and copy the Central Reports related settings into your server.properties file.

As an example, if using Microsoft SQL Server as the external database, the following statements configure a Melbourne application server to run consolidated reports across the Melbourne, Perth and Sydney sites:

                central-reports.enabled=Y
                               
                               
                central-reports.database.local.include=Y
                central-reports.database.local.label=Melbourne HQ
                
                central-reports.require-all-databases-online=Y 
                
                central-reports.database.1.label=Perth Branch
                central-reports.database.1.url=jdbc:jtds:sqlserver://per1.example.com/papercut
                central-reports.database.1.username=admin
                central-reports.database.1.password=xJf56gy

                central-reports.database.2.label=Sydney Branch
                central-reports.database.2.url=jdbc:jtds:sqlserver://syd1.example.com/papercut
                central-reports.database.2.username=admin
                central-reports.database.2.password=dF95FCd

Note that in this example the server.properties file is for the "Melbourne HQ" site, and it would contain configuration for its own SQL Server database above (as documented in the section called “Upsizing to an External RDBMS”).

The database statements detailed below must be specified for each remote server. Where specified, n is a numeric ID (e.g: 1, 2, 3) used to associate statements for the same site, as per the example above.

Key	Description
central-reports.enabled	Central Reports is enabled (but not configured) by default. The purpose of this setting is to allow you to disable Central Reports if required. This will result in users not being able to log into the Central Reports interface, and scheduled Central Reports will not run. Values: Y or N. Default: Y.
central-reports.database.local.include	Specify whether to include the local server in the aggregated Central Reports. Values: Y or N. Default: Y. You would specify N if your local server was set up for running reports only and is not to be used as a PaperCut application server.
central-reports.database.local.label	Provide a meaningful name for the local site. Default: "Local Site".
central-reports.require-all-databases-online	This option configures whether or not all databases must be online to create reports. If set to N, reports are created even if some remote databases are not available, but the aggregated reports will not include data from those databases. Values: Y or N. Default: Y.
central-reports.database.n.label	A text label to identify the remote server n, in the Central Reports status page and reports.
central-reports.database.n.url	Specify the JBDC URL providing remote access to your database. This URL is specified in the same way as for the external database you have already configured on this system.
central-reports.database.n.username	A database username providing read access to the remote database.
central-reports.database.n.password	A database password for the supplied username.

Table 10.2. Central Reports statements in server.properties

Running Central Reports

Access Central Reports at the URL https://[server-name]:9192/central-reports. You will see two tabs:

Status - check the remote server status and whether you are ready to run reports
Reports - generate on-demand and scheduled reports

Status Tab

The Status Tab shows the status of each configured remote servers and displays any errors that may prevent Central Reports from running.

Figure 10.6. Central Reports Status Tab

Reports may not be generated if any server has an error. Typical errors include:

Failing to connect to the database (incorrect authentication, firewall blocking access, configuration error).
Servers have mis-matched application versions or database types.

Central Reports Tab

The Central Reports tab shows the reports available under Central Reports and allows reports to be generated on demand or to be scheduled for email delivery. Central Reports provides a sub-set of the reports available in the admin Reports interface, but the usage is the same. Please refer to Chapter 9, Reports for instructions on how to run reports and configure filters.

Select the Schedule / Email Reports tab to schedule Central Reports for periodic generation and automatically have them emailed to the appropriate people in your organization.