JasperReports Server Community Project Administrator Guide Jasper Reports CP Admin

User Manual:

Open the PDF directly: View PDF .
Page Count: 208

Download
Open PDF In Browser	View PDF

TIBCO JasperReports® Server
Community Project
Administrator Guide
Software Release 7.2

Important Information
SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED OR BUNDLED TIBCO
SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED
TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO
SOFTWARE OR FOR ANY OTHER PURPOSE.
USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A LICENSE AGREEMENT
FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE
AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF
THE SOFTWARE (AND WHICH IS DUPLICATED IN THE LICENSE FILE) OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT
OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE “LICENSE” FILE(S) OF THE SOFTWARE. USE OF
THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF
AND AN AGREEMENT TO BE BOUND BY THE SAME.
ANY SOFTWARE ITEM IDENTIFIED AS THIRD PARTY LIBRARY IS AVAILABLE UNDER SEPARATE SOFTWARE LICENSE TERMS AND
IS NOT PART OF A TIBCO PRODUCT. AS SUCH, THESE SOFTWARE ITEMS ARE NOT COVERED BY THE TERMS OF YOUR
AGREEMENT WITH TIBCO, INCLUDING ANY TERMS CONCERNING SUPPORT, MAINTENANCE, WARRANTIES, AND INDEMNITIES.
DOWNLOAD AND USE OF THESE ITEMS IS SOLELY AT YOUR OWN DISCRETION AND SUBJECT TO THE LICENSE TERMS
APPLICABLE TO THEM. BY PROCEEDING TO DOWNLOAD, INSTALL OR USE ANY OF THESE ITEMS, YOU ACKNOWLEDGE THE
FOREGOING DISTINCTIONS BETWEEN THESE ITEMS AND TIBCO PRODUCTS.
This document is subject to U.S. and international copyright laws and treaties. No part of this document may be reproduced in any form without the
written authorization of TIBCO Software Inc.
TIBCO, the TIBCO logo, Jaspersoft, JasperReports, and Visualize.js are registered trademarks of TIBCO Software Inc. in the United States and/or other
countries.
Java and all Java based trademarks and logos are trademarks or registered trademarks of Oracle and/or its affiliates.
All other product and company names and marks mentioned in this document are the property of their respective owners and are mentioned for
identification purposes only.
THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.
THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY
ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO
SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN
THIS DOCUMENT AT ANY TIME.
THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR INDIRECTLY, BY OTHER
DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ
ME" FILES.
This and other products of TIBCO Software Inc. may be covered by registered patents. Please refer to TIBCO's Virtual Patent Marking document
(https://www.tibco.com/patents) for details.
Copyright © 2005-2019. TIBCO Software Inc. All Rights Reserved.

Version 0619-JSO72-05 of the JasperReports Server Community Project Administrator Guide

TABLE OF CONTENTS
Chapter 1 Overview of JasperReports Server Administration
1.1 Overview of the Repository
1.1.1 Folder Structure
1.1.2 Resources
1.1.3 Browsing and Searching
1.2 Overview of Users and Roles
1.2.1 Administering Users and Roles
1.2.2 Delegated Administration
1.3 Overview of Security
1.4 Administrator Login
1.4.1 JasperReports Server Heartbeat
1.4.2 Administrator Email
1.5 Administrator Pages
Chapter 2 User and Role Management
2.1 Managing Users
2.1.1 Viewing User Properties
2.1.2 Creating a User
2.1.3 Editing a User
2.1.4 Enabling or Disabling Multiple Users
2.1.5 Deleting One or More Users
2.2 Managing Roles
2.2.1 Viewing Role Properties
2.2.2 Creating a Role
2.2.3 Assigning Users to a Role
2.2.4 Deleting One or More Roles
2.3 Managing Attributes
2.3.1 Referencing Attributes
2.3.2 Attribute Hierarchy
2.3.3 Attribute Encryption
2.3.4 Attribute Permissions
2.3.5 Managing Server Attributes
2.3.6 Managing User Attributes

TIBCO Software Inc.

9
10
10
11
11
12
13
13
13
15
15
15
16
17
17
18
18
19
20
21
21
21
22
23
23
24
24
24
25
25
26
27

JasperReports Server Community Project Administrator Guide

Chapter 3 Repository Administration
3.1 Resource Types
3.2 JasperReport Structure
3.2.1 Referencing Resources in the Repository
3.2.2 Absolute References
3.2.3 Local Resources and External References
3.2.4 References in Subreports
3.2.5 Data Snapshots
3.3 Managing Folders and Resources
3.3.1 Resource IDs
3.3.2 Creating Folders
3.3.3 Adding Resources
3.3.4 Renaming Folders and Resources
3.3.5 Copying and Moving
3.3.6 Editing Resources
3.3.7 Deleting Folders and Resources
3.4 Repository Permissions
3.4.1 Inheriting Permissions
3.4.2 Cumulative Permissions
3.4.3 Administrator Permissions
3.4.4 Execute-Only Permission
3.4.5 Default User Permissions
3.4.6 Setting Permissions
3.4.7 Testing User Permissions
Chapter 4 Data Sources
4.1 Attributes in Data Source Definitions
4.2 JDBC Data Sources
4.3 Managing JDBC Drivers
4.4 JNDI Data Sources
4.5 AWS Data Sources
4.5.1 Creating an AWS Data Source
4.5.2 Filtering the Regions For AWS Data Source
4.6 Azure SQL Data Sources
4.6.1 Uploading an Azure Certificate File to the Repository
4.6.2 Creating an Azure SQL Server Data Source
4.7 Cassandra Data Sources
4.7.1 Creating a Cassandra Data Source with the Native Cassandra Driver
4.7.2 Increasing File Descriptor Limits for Cassandra
4.8 MongoDB Data Sources
4.8.1 Creating a MongoDB Data Source with the Native MongoDB Driver
4.8.2 Creating a MongoDB JDBC Data Source
4.8.3 Using Kerberos Authentication with MongoDB Data Sources
4.8.4 Creating a Schema with the Schema Tool
4.8.5 Uploading a Schema to the Repository
4.9 File Data Sources

31
31
33
33
34
34
35
35
36
36
37
37
38
39
40
41
41
43
43
43
43
44
44
46
47
48
50
52
55
56
57
59
59
60
60
62
62
63
64
64
66
68
69
69
69

TIBCO Software Inc.

4.10 Bean Data Sources
Chapter 5 Other Resources in the Repository
5.1 Queries
5.2 Datatypes
5.3 Lists of Values
5.4 Input Controls
5.5 Query-based Input Controls
5.5.1 Creating a Query-based Input Control
5.5.2 Built-in Parameters for Query-based Input Controls
5.6 Cascading Input Controls
5.6.1 Parameters in Input Control Queries
5.6.2 Creating a Cascading Input Control
5.7 File Resources
5.7.1 Fonts
5.7.2 JAR Files
5.7.3 Resource Bundles
5.7.4 Creating a File Resource
5.7.5 Editing a File Resource
5.7.6 Uploading an SSH Private Key File to the Repository
Chapter 6 Themes
6.1 Introduction to Themes
6.2 How Themes Work
6.2.1 Theme Files
6.2.2 Inheritance
6.2.3 CSS Priority Scheme and Custom Overrides
6.3 Administering Themes
6.4 Creating Themes
6.4.1 Creating Theme Folders and File Resources
6.4.2 Downloading and Uploading Theme ZIP Files
6.5 Working With CSS Files
6.5.1 Theme Development Workflow
6.5.2 Firefox Web Developer Tools
6.5.3 Test Platform
6.5.4 Modifying the Appearance of Jaspersoft OLAP
Chapter 7 Import and Export
7.1 Import and Export Catalogs
7.1.1 Dependencies During Import and Export
7.1.2 Setting the Import-Export Encryption Key
7.1.3 Importing Unencrypted Catalogs
7.2 Import and Export Through the Web UI
7.2.1 Exporting From the Repository
7.2.2 Exporting From the Settings
7.2.3 Importing From the Settings
7.3 Import and Export Through the Command Line

TIBCO Software Inc.

72
75
75
77
78
79
82
82
86
87
88
89
93
94
95
95
95
96
97
99
99
100
101
102
102
103
105
105
106
107
108
108
109
109
111
111
112
112
113
113
113
115
117
119

JasperReports Server Community Project Administrator Guide

7.3.1 Exporting From the Command Line
7.3.2 Importing From the Command Line
7.3.3 Configuring Import-Export Utilities
7.4 Alternate Import-Export Scripts
7.4.1 Running Import from Buildomatic
7.4.2 Running Export from Buildomatic
Chapter 8 System Configuration
8.1 Configuration Settings in the User Interface
8.1.1 Understanding Persistent Settings
8.1.2 Restoring Default Settings
8.2 Configuration for Using Proxies
8.3 Configuration for Session Persistence
8.4 Enabling Data Snapshots
8.4.1 Global Data Snapshot Configuration
8.4.2 Report-level Data Snapshot Configuration
8.4.3 Data Snapshots in the Scheduler
8.5 Configuring Cloud Services
8.5.1 Changing Cloud Services Settings
8.5.2 Changing the Default JDBC Driver for AWS Data Sources
8.5.3 Changing Azure SQL Data Source Defaults
8.6 Configuring JasperReports Library
8.6.1 Extending JasperReports Library
8.6.2 Changing the Crosstab Limit
8.6.3 Setting a Global Chart Theme
8.6.4 Disabling Interactivity in the Report Viewer
8.6.5 Disabling Chart Types in Dashboards
8.6.6 Changing the Pro Charts Rendering Engine
8.6.7 Configuring a JavaScript Engine for Graphical Report Rendering
8.6.8 Static Export Properties for High Charts
8.6.9 Enabling PDF Accessibility Features in Tables
8.7 Configuring Input Control Behavior
8.8 Configuring the Scheduler
8.8.1 Configuring the Scheduler Misfire Policy
8.8.2 Configuring Scheduler Failure Notifications
8.8.3 Restricting File System Output
8.8.4 Removing Report Scheduling Interval Options
8.8.5 Adding a Holiday Exclusion Calendar
8.8.6 Changing the Default Output Folder
8.9 Configuring Report Thumbnails
8.10 Configuring the Heartbeat
8.11 Configuring the Online Help
Chapter 9 Configuring System Logs
9.1 Log File Location
9.2 Managing Log Settings
9.3 Log Configuration Files

119
121
123
124
124
125
127
128
129
129
130
131
133
133
134
135
135
136
137
137
138
139
139
139
140
141
141
142
144
145
145
146
146
147
148
149
150
152
152
152
153
155
155
155
157

TIBCO Software Inc.

9.4 Adding a Logger to the Log Settings Page
Appendix A Troubleshooting
A.1 Number of Users Exceeded
A.2 Running Out of Database Connections
A.3 Custom URLs Not Loading in Dashboards
A.4 Print View Not Displaying in Dashboards
A.5 Scheduler Sending Multiple Emails
A.6 Scheduler Not Sending STARTTLS Emails
A.7 Scheduler Running Deleted Jobs
A.8 Scheduler Timezones in Excel Output
A.9 Charts Not Appearing in Excel Export
A.10 Working With Data Sources
A.10.1 Logging JDBC Operations
A.10.2 JDBC Drivers
A.10.3 Database Permissions
A.10.4 JDBC Database URLs
A.10.5 SQL Functions with TIBCO JDBC Drivers
A.10.6 Enabling the TIBCO JDBC Drivers for Impala and Cassandra Data Sources
A.10.7 JNDI Services on Apache Tomcat
A.10.8 JNDI Services on JBoss
A.10.9 JNDI Services on WebLogic
A.10.10 Creating a Data Source on SQL Server Using Windows Authentication
A.10.11 Upgrading Bean Data Sources
A.11 Special Characters in Database Schemas
A.12 Cassandra Reports Not Running
A.13 Maximum Parameter Size in Wildfly
Appendix B Localization
B.1 Configuring JasperReports Server for Multibyte Fonts
B.1.1 Enabling East Asian Fonts
B.1.2 Configuring Ad Hoc Charts for Asian Fonts
B.1.3 Configuring OLAP Options for Chart Default Fonts
B.1.4 Embedding Fonts in PDF Output for OLAP Views
B.2 UTF-8 Configuration
B.2.1 Java Options
B.2.2 Tomcat
B.2.3 PostgreSQL
B.2.4 MySQL
B.2.5 JBoss
B.2.6 Oracle
B.3 Changing Character Encoding
B.3.1 Configuring JasperReports Server
B.3.2 Configuring the Application Server and Database Server
B.3.3 Configuration for Localized Analysis Schemas
B.4 Creating a Locale
B.4.1 About Properties Files

TIBCO Software Inc.

158
161
161
162
162
163
163
164
164
165
165
165
166
166
166
167
168
168
169
170
170
171
171
173
174
174
175
175
176
177
178
178
179
179
179
180
180
180
181
181
182
182
182
183
183

JasperReports Server Community Project Administrator Guide

B.4.2 Creating a Resource Bundle
B.4.3 Setting Date and Datetime Formats
B.5 Configuring JasperReports Server to Offer a Locale
B.5.1 Specifying Additional Locales
B.5.2 Specifying Additional Time Zones
B.5.3 Setting a Default Time Zone

185
186
186
187
187
188

Glossary

191

Index

203

TIBCO Software Inc.

CHAPTER 1

OVERVIEW OF JASPERREPORTS SERVER ADMINISTRATION

TIBCO JasperReports® Server builds on TIBCO JasperReports® Library as a comprehensive family of Business
Intelligence (BI) products, providing robust static and interactive reporting, report server, and data analysis
capabilities. These capabilities are available as either stand-alone products, or as part of an integrated end-to-end
BI suite utilizing common metadata and provide shared services, such as security, a repository, and scheduling.
The server exposes comprehensive public interfaces enabling seamless integration with other applications and
the capability to easily add custom functionality.
The heart of the TIBCO Jaspersoft® BI Suite is the server, which provides the ability to:
•
•
•
•
•

Easily create new reports based on views designed in an intuitive, web-based, drag and drop Ad Hoc
Editor.
Efficiently and securely manage many reports.
Interact with reports, including sorting, changing formatting, entering parameters, and drilling on data.
Schedule reports for distribution through email and storage in the repository.
Arrange reports and web content to create appealing, data-rich Jaspersoft Dashboards that quickly convey
business trends.

For users interested in multi-dimensional modeling, we offer Jaspersoft® OLAP, which runs as part of the server.
While the Ad Hoc Editor lets users create simple reports, more complex reports can be created outside of the
server. You can either use Jaspersoft® Studio or manually write JRXML code to create a report that can be run
in the server. We recommend that you use Jaspersoft Studio unless you have a thorough understanding of the
JasperReports file structure.
You can use the following sources of information to learn about JasperReports Server:
•

•

Our core documentation describes how to install, administer, and use JasperReports Server and Jaspersoft
Studio. Core documentation is available as PDFs in the doc subdirectory of your JasperReports Server
installation. You can also access PDF and HTML versions of these guides online from the Documentation
section of the Jaspersoft Community website.
Our Ultimate Guides document advanced features and configuration. They also include best practice
recommendations and numerous examples. You can access PDF and HTML versions of these guides online
from the Documentation section of the Jaspersoft Community website.
Our Online Learning Portal lets you learn at your own pace, and covers topics for developers, system
administrators, business users, and data integration users. The Portal is available online from the Professional
Services section of our website.
Our free samples, which are installed with JasperReports Library, Jaspersoft Studio, and JasperReports
Server, are available and documented online. Please visit our GitHub repository.

TIBCO Software Inc.

JasperReports Server Community Project Administrator Guide

This administrator guide describes features that are only available to users who have administrator roles.
Many of the configuration procedures also assume you have access to the installed files on the host
computer.

•

If you have a subscription to our professional support offerings, please contact our Technical Support team
when you have questions or run into difficulties. They're available on the web at and through email at
http://support.tibco.com and js-support@tibco.com.

This chapter contains the following sections:
•
•
•
•
•

Overview of the Repository
Overview of Users and Roles
Overview of Security
Administrator Login
Administrator Pages
This section describes functionality that can be restricted by the software license for JasperReports
Server. If you don't see some of the options described in this section, your license may prohibit you from
using them. To find out what you're licensed to use, or to upgrade your license, contact Jaspersoft.

JasperReports Server is a component of both a community project and commercial offerings. Each integrates the
standard features such as security, scheduling, a web services interface, and much more for running and sharing
reports. Commercial editions provide additional features, including Ad Hoc charts, dashboards, Domains,
auditing, and a multi-organization architecture for hosting large BI deployments. This guide documents the
features of the community project.

1.1

Overview of the Repository
The repository is a hierarchical structure of folders where administrators and users create and store resources for
running reports. In its appearance and function, the repository resembles a file system with a structure of folders
containing files. However, the repository is actually implemented as a database that is private to the server
instance. As a result, it lacks a few of the functions of a file system.

1.1.1

Folder Structure
The repository is a tree structure composed of folders and resources. The root contains folders for the sample
data installed with the server.

Figure 1-1 Root of the Repository Showing Default Folders

TIBCO Software Inc.

Chapter 1 Overview of JasperReports Server Administration

In general, we recommend that you avoid placing resources directly in the root. Instead, use folders for various
resource types, as in the sample data. The Themes folder contains files that control the look and feel of the user
interface, as described in Chapter 6, “Themes,” on page 99.

1.1.2

Resources
Resources are stored in the repository and used as input for creating reports and performing analysis. Some
resources, such as images, fonts, or JRXML files created in Jaspersoft Studio, are uploaded from files. Others,
such as data sources and Domains, are created in JasperReports Server itself. Of course, dashboards, data views,
and reports can also be saved in the repository to be run as often as needed. Output such as PDF or HTML can
be saved in the repository as well.
All resources, including folders, have unique IDs, names, and optional descriptions. The ID of a resource, along
with the ID of its enclosing folders create the path used to reference that resource. The path of a resource is also
called its repository URI (Universal Resource Indicator). The name and description appear in the user interface
when you browse or search the repository.
Resources are stored in an internal format not accessible to users or administrators. Any resource can be exported
with the js-export utility, but the resulting files are for backup or transfer to another JasperReports Server
instance and cannot be modified.
JasperReports Server restricts access to folders and resources based on organizations, permissions, user names,
and roles. For more information, see Chapter 3, “Repository Administration,” on page 31.
The sample data includes dashboards, reports, Domains, data sources, and many of their components, such as
input types and image files. Each type of content is stored in a separate folder, making it easy to locate. The
Supermart Demo folder contains a complete example of dashboards, reports, and resources for various business
scenarios in a fictional grocery store company.

1.1.3

Browsing and Searching
Users and administrators can browse or search the repository, depending on what action they want to perform
and how resources are organized. Searching the repository finds specific resources faster. For more information
on browsing and searching the repository, see the JasperReports Server User Guide.
•

Browsing - On the Home page, click View > Repository.
The Folders panel on the left lists the folders in the repository and the Repository panel lists the contents of
the selected folder. The tool bar in the Repository panel allows administrators to perform actions such as
Copy, Cut, Paste, and Delete; select several resources with Control-click or Shift-click to perform actions
in bulk.

TIBCO Software Inc.

JasperReports Server Community Project Administrator Guide

Figure 1-2 Browsing the Repository
•

Searching - Enter a search term in the search field at the top of any page, or select View > Search Results.

Figure 1-3 Search Field in the Menu Bar
The search results page displays a search field with the current search term at the top of the Repository
panel. The search applies to resource IDs, names, and descriptions. Use the filters in the left-hand panel to
refine your search.

Figure 1-4 Searching the Repository

1.2

Overview of Users and Roles
User accounts and role membership provide authentication and authorization for access control in JasperReports
Server. When logging, in users enter their username and password to access the server. Administrators assign
named roles to users and then create role-based permissions to further control access to the repository.

TIBCO Software Inc.

Chapter 1 Overview of JasperReports Server Administration

Administrators define permissions directly on the resources and folders in the repository. You can define a level
of access, such as read-write, read-only, or no access, and assign each permission based on either a username or a
role.

1.2.1

Administering Users and Roles
Administrators perform the following actions to manage users:
•
•
•
•
•
•
•

1.2.2

Create, modify, and delete users.
Set user account properties such as name, email, and attributes.
Reset a user password. However, no administrator can ever view a user's existing password.
Login as any user to test permissions.
Create, modify, and delete roles.
Assign roles to users.
Set access permissions on repository folders and resources.

Delegated Administration
JasperReports Server enables two levels of delegated administration:
•
•

1.3

The Administer permission allows a user to view and set permissions on a folder or resource. This can allow
a power-user to manage a section of the repository, but not to create or manage users.
Granting ROLE_ADMINISTRATOR allows a user to see the management interface and create users and roles.
This is true delegated administration, whereby a user other than jasperadmin has administration abilities.

Overview of Security
JasperReports Server ensures that people can access only the data they are allowed to see. The mechanisms that
define users, roles, and repository resources work together to provide complete access control. Security has many
facets covered in this guide and other guides:
Authentication

Authentication is the process of restricting access to identified users. Users must log
in with their user ID and password so that they have an identity in JasperReports
Server. The server stores user definitions, including encrypted passwords, in a
private database. Administrators create, modify, and delete user accounts through
the administrator pages, as described in 2.1, “Managing Users,” on page 17.

Password policies

Every company must establish a password policy that weighs its security risks
against the convenience of its users. JasperReports Server supports many different
password policies such as password expiration, reuse, and strong patterns. This
configuration is described in the JasperReports Server Security Guide.

External authentication

External authentication uses centralized identity services such as LDAP (used by
Microsoft Active Directory and Novell eDirectory), Central Authentication Service
(CAS), or Java Authentication and Authorization Service (JAAS). For more
information, see the JasperReports Server External Authentication Cookbook.

TIBCO Software Inc.

JasperReports Server Community Project Administrator Guide

Application Security

System admins who install and maintain enterprise software know they must protect
their servers against hackers. JasperReports Server protects your data against
intruders with many protocols and tools, such as HTTPS, encryption, CSRF
prevention, and input validation against cross-site scripting and SQL injection. For
these topics and others, see the JasperReports Server Security Guide.

Roles

JasperReports Server also implements roles that can be assigned to any number of
users. Roles let administrators create groups or classes of users that are granted
similar permissions. A user may belong to any number of roles and receive the
privileges from each of them. Administrators create, modify, and delete roles
through the administrator pages, as described in 2.2, “Managing Roles,” on
page 21.

Resource permissions

Administrators can define access permissions on every folder and resource in the
repository. Permissions are enforced when accessing any resource either directly
through the repository interface, indirectly when called from a report, or
programmatically through the web services.
Permissions can be defined for every role and every user, or they can be left
undefined so they are inherited from the parent folder. To restrict access or hide
resources such as database connections, the administrator can set no-access or
execute-only permission. For more information, see 3.4, “Repository
Permissions,” on page 41.

Administrator privileges

JasperReports Server distinguishes between administrators and users.
Administrators are granted access to the UI for permissions, user management, and
sensitive resources such as database connections. Administrators also set the UI
appearance with themes. Regular users are restricted to the folders, reports, and
dashboards that admins allow them to access. Most of the features in this guide are
not accessible to regular users. See 1.2.2, “Delegated Administration,” on
page 13.

Menus and pages

The menus that appear in JasperReports Server depend on the user's roles. For
example, only users with the administrator role can see the Manage menu and
access the administrator pages. By modifying the server's configuration, you can
modify access to menus, menu items, and individual pages. Refer to the
JasperReports Server Community Project Source Build Guide and JasperReports
Server Ultimate Guide for more information.

Attributes

Attributes are name-value pairs associated with a user, organization, or server.
Attributes can be used to restrict or enable a user's access to data in several ways.
See 2.3, “Managing Attributes,” on page 24.

Administrators must keep security in mind at all times when managing user, roles, and resources, because
effective security relies on all of them working together.

TIBCO Software Inc.

Chapter 1 Overview of JasperReports Server Administration

1.4

Administrator Login
Administrators log in on the standard login page, using the following default password:
Administrator:

user ID jasperadmin and password jasperadmin

For security reasons, always change the default administrator password immediately after installing
JasperReports Server. For instructions, see 2.1.3, “Editing a User,” on page 19.

For more information about options on the Login page and logging in with multiple organizations, see the
JasperReports Server User Guide.
The first time you log in as an administrator, you may be prompted to opt-into the Heartbeat program. You
should also set the administrator passwords and email.

1.4.1

JasperReports Server Heartbeat
When you log into JasperReports Server for the first time after installation, administrators may be prompted to
opt into the server's Heartbeat program. It reports specific information to Jaspersoft about your implementation:
the operating system, JVM, application server, database (type and version), and JasperReports Server edition and
version number. By tracking this information, we can build better products that function optimally in your
environment. No personal information is collected.
To opt into the program, click OK. To opt out, clear the check box then click OK.

1.4.2

Administrator Email
After logging in for the first time, you should set the email on the jasperadmin account to your email address.
In rare cases, the server may notify you by email about issues with your license.
This is also a good time to change the default passwords on the jasperadminaccount.

To set the email and passwords on the administrator account, edit the user account information as described in
2.1.3, “Editing a User,” on page 19.

TIBCO Software Inc.

JasperReports Server Community Project Administrator Guide

1.5

Administrator Pages
Administrators have access to special pages to manage the server. After logging in, select an item from the
Manage menu on any page.

Figure 1-5 Manage Menu for Administrators
The pages for administering users and roles are documented in Chapter 2, “User and Role Management,” on
page 17. The pages for administering Server Settings are documented in 8.1, “Configuration Settings in the
User Interface,” on page 128.
The About TIBCO JasperReports Server link in the footer of all pages displays the product version along
with the software build.

Figure 1-6 About TIBCO JasperReports Server Dialog

TIBCO Software Inc.

CHAPTER 2

USER

AND

ROLE MANAGEMENT

Administrators create users, assign them to roles, and optionally define attributes for them. The interface in
JasperReports Server for managing users and roles makes it easy to search among hundreds of users and roles
and edit their properties.
Attributes are name-value pairs that can be defined on users and at the server level. These values can provide
flexibility, for example allowing each user to access a different database when using the same data source.
Attributes can provide data-level security when combined with the features of Domains and OLAP.
This chapter contains the following sections:
•
•
•

2.1

Managing Users
Managing Roles
Managing Attributes

Managing Users
Administrators create and manage all users in the server, including creating other administrators, as described in
1.2.2, “Delegated Administration,” on page 13.
The default installation of JasperReports Server includes the following users:
Table 2-1 Default Users after Installation
User Name

Default Password
(case sensitive)

Description

jasperadmin

Default administrator.

joeuser

Default end user.

anonymousUser

anonymoususer

Allows anonymous login; disabled by default. If you do
not allow anonymous access, this user can be deleted.

TIBCO Software Inc.

JasperReports Server Community Project Administrator Guide

In light of security concerns, we recommend that you remove any users that are not being used in your
instance, whether created by default or otherwise.
Advise your users to change their passwords regularly. To configure periodic expiration of passwords,
refer to the JasperReports Server Security Guide.

2.1.1

Viewing User Properties
1.

Select Manage > Users . The Manage Users page displays the users and properties of the selected user.

Figure 2-1 Manage Users Page
The columns in the Users panel list the user ID and the user name of each user in the server
3.

To locate a user:
• Browse for users – Scroll through the list of users if it is too long to fit on your screen.
• Search for a user – Enter a search string in the Search field of the Users panel. The search results show
all user ID or names that match the search string.
Select a user account to view its Properties in the right-hand panel.
User status can be Enabled or Disabled; disabled users are displayed in gray text in the Users list. For
convenience, the role names link to the role management page for each role. For information about
attributes on the user, see 2.3.6, “Managing User Attributes,” on page 27.

2.1.2

Creating a User
1.

Select Manage > Users.

Click Add User. The Add User dialog appears.

TIBCO Software Inc.

Chapter 2 User and Role Management

Figure 2-2 Adding a User
4.

Enter the following information:
• User name – The new user's full name. The name is optional but recommended; It will appear in the
menu bar of the UI when the user is logged in.
• User ID – Generated automatically from the user name; you can accept the suggested value or type
your own. The user ID is used to log into JasperReports Server, and for administrators to manage users
and resources. The User ID must be unique.
• Email – This is optional but must be in a valid email format.
• Password and confirmation – Enter and confirm a password for the user.
• User is enabled – To enable the user to log in, select this check box. Users who are not enabled can't
log in. If you implement role-based permissions, you might want to delay enabling the user until you
assign more roles. For more information on roles, see 2.2, “Managing Roles,” on page 21.
Click Add User.
The new user is available in the Users panel. To assign roles to the user, click Edit in the user's Properties
panel.

2.1.3

Editing a User
One way to assign roles to a user is to edit the user's properties. Alternatively, when you edit a role, you can
assign it to any number of users. To edit a user's properties:
1.

2.
3.

Click Manage > Users.
In the Users panel, select the user.

In the user's Properties panel, click Edit.

TIBCO Software Inc.

JasperReports Server Community Project Administrator Guide

Figure 2-3 Editing the Properties of a User

2.1.4

Edit the user's properties as needed. You can't edit the user ID; it always has the value defined when the
user was created originally.

To assign or remove roles from the user, select the roles, and use the arrow buttons between the Roles
Available and Roles Assigned lists.

For information about attributes on the user, see 2.3.6, “Managing User Attributes,” on page 27.

Click Save to keep your changes.

In the Properties panel, click Login as User to test the user's permissions, as explained in 3.4.7, “Testing
User Permissions,” on page 46.

Enabling or Disabling Multiple Users
You may sometimes need to disable user accounts. For example, when making configuration changes, you may
want to lock out all users until the changes are finished. The administrator (jasperadmin) can select any
number or all of the users, except himself.

2.
3.

Click Manage > Users.
In the Users list, use Control-click and Shift-click to make multiple selections. If the User list is too long,
enter a search term to find users and enable or disable them individually.

Click Enable or Disable in the menu bar.

TIBCO Software Inc.

Chapter 2 User and Role Management

2.1.5

2.2

Deleting One or More Users
1.

2.
3.

Click Manage > Users.
In the Users list, use Control-click and Shift-click to make multiple selections. If the list of users is too long,
enter a search term to find and select the user.

In the tool bar of the Users panel, click Delete and confirm the action.

Managing Roles
Roles define sets of users who are granted similar permissions. Administrators create roles, assign them to users,
and set permissions in the repository (see 3.4, “Repository Permissions,” on page 41). By default,
JasperReports Server includes the following roles; some are needed for system operation, some are included as
part of the sample data:
Table 2-2 Default Roles in JasperReports Server Installations
Role

Description

ROLE_ADMINISTRATOR

This role determines administrator privileges. This role is automatically
assigned to the default jasperadmin user. It's a special system-level role,
and administrators can assign it to other users, as explained in 1.2.2,
“Delegated Administration,” on page 13.
Never delete this role, it's required for proper administration of the server.

ROLE_USER

Required to log in. This role is automatically assigned to every user in the
server. It's a special system-level role.
Never delete this role, it's required to create users and allow them to log in.

ROLE_ANONYMOUS

When anonymous access is enabled, this role is automatically assigned to
any agent accessing the server without logging in. It's a special systemlevel role. This role is also assigned to the default anonymous user. By
default, anonymous access is disabled and this role isn't used. It's a system
role that even administrators can't delete.

When you need to define permissions for sets of users, administrators can create new roles and assign them to
users. Users can belong to any number of roles and each can be used for access to different resources.

2.2.1

Viewing Role Properties
1.

Select Manage > Roles. The Manage Roles page displays the roles defined in the server and properties for
each role.

TIBCO Software Inc.

JasperReports Server Community Project Administrator Guide

Figure 2-4 Manage Roles Page
3.

To filter the list of roles, enter a search string in the search field of the Roles panel. The search results show
all of the roles whose names contain the search string. If necessary, scroll through the new list or refine your
search.

Select the role in the Roles panel. The role's properties appear in the Properties panel.
The Properties panel shows the role name and the users assigned to the role. You can enter a search term to
find users in the list. Hover over a user ID to see a user's full name, as shown in the figure.

2.2.2

Creating a Role
1.

Select Manage > Roles.

Click Add Role. The Add Role dialog appears.

Figure 2-5 Adding a Role
4.

Enter the name of the role. The role name is also the role ID and does not accept spaces or special
characters.

Click Add Role to create the role.
The new role is included in the Roles panel. If you want to assign users to the role, click Edit in the
Properties panel of the new role.

TIBCO Software Inc.

Chapter 2 User and Role Management

2.2.3

Assigning Users to a Role
You can assign multiple users to one role. To assign multiple roles to one user, edit the user's properties as
described in 2.1.3, “Editing a User,” on page 19.
1.

2.
3.

Select Manage > Roles.
Select the role in the Roles panel.

In the Properties panel, click Edit. The role's properties become editable.

Figure 2-6 Editing the Members of a Role
5.

Enter a different name to change the role name throughout the server.
Permissions in the repository that use the role name are automatically updated. However, role names in
security files for Domains and OLAP are not updated with the new role name and may cause a security
risk. If you use security files for Domains or OLAP, do not change role names without verifying the files as
well. For more information, see the JasperReports Server User Guide.

2.2.4

To assign or remove role users, select the users, and click the arrow buttons between the Users Available
and Users Assigned lists. You can enter a search term to find users in the lists. Hover over a user ID to see a
user's full name, as shown in the figure.

Click Save to keep your changes, or Cancel to quit without saving.

Deleting One or More Roles
1.

2.
3.

Select Manage > Roles.
Select the role in the Roles panel. Use Control-click and Shift-click to make multiple selections.

In the tool bar of the Roles panel, click Delete and confirm the action.

TIBCO Software Inc.

JasperReports Server Community Project Administrator Guide

2.3

Managing Attributes
Attributes are name-value pairs that are associated with users and the server itself. Attribute values can be used
to parameterize access to data sources OLAP data, and report output. Attributes were previously known as
profile attributes.
Attributes have permissions, so that administrators can restrict the visibility and use of specific attributes.
The permission feature of attributes is designed to work with multiple organizations in commercial
editions of JasperReports Server. The feature is enabled in all editions of the server, but has limited use
in the Community Project edition.

2.3.1

Referencing Attributes
There are several features of JasperReports Server that can read attributes and use attribute values. The following
features can limit or restrict access to data or take different behavior based on the user or server-level attributes.
Each feature reads or references attributes in its own syntax that is described with that feature:
•
•
•

Data sources – The host name, port number, database name, user name and user password can be defined
through attributes. See 4.1, “Attributes in Data Source Definitions,” on page 48.
Reports – Attribute values can be referenced in calculations as described in Table 5-2, “Attribute-based
Parameters for Queries and Reports,” on page 87.
OLAP schemas – Similar to Domains, access rules can be defined with attributes so that users may only see
data they are allowed to access. See the Jaspersoft OLAP User Guide.

Attributes are always referenced in relation to the currently-logged in user who is performing an operation or
running a report:
•
•

2.3.2

If the value of a user-level attribute is requested, it refers to the attributes of the logged-in user.
If the value of a server-level attribute is requested, the value depends on which server the user is logged
into. For example, test and production servers may have a copy of the same repository, but different serverlevel attributes. For a given server, server-level attributes are shared and thus have the same value for all
users.

Attribute Hierarchy
An attribute is a named value that is defined on a user or root of the server. Any number of attributes with any
name can be defined at either or both of these levels. The definition of each attribute at each level is
independent of other attributes at other level. Attributes at different levels may have the same name, unless
explicitly forbidden as described in 2.3.4, “Attribute Permissions,” on page 25.
In the places that you reference attributes (see above), there are two ways to determine the value of an attribute:
•
•

Categorical value – References the value of a named attribute at a specific level, either user level or server
level. If the attribute does not exist at the requested level, no value is returned.
Hierarchical value – References the value of a named attribute across all levels, starting at the user level.
The server searches for an attribute with the given name in the following order, stopping and returning the
first value that it finds:
• At the user level, in the user attributes of the logged-in user.
• At the server level.
• If the attributes does not exist at any level, no value is returned.

TIBCO Software Inc.

Chapter 2 User and Role Management

With hierarchical values, attributes with same name but different values may be defined at several levels and on
many users. Each attribute is a distinct attribute definition, but the hierarchical value referencing takes into
account the level and the presence of the definition for every given user.
To help administrators define attributes on users, the UI displays all attributes that are visible in the attribute
hierarchy. If an attribute is defined at the server level, its hierarchical value is shown at the user level, and the
attribute is called inherited. This allows the administrator to see all hierarchical values that are in effect in lower
levels, either to override them in the hierarchy or leave them as inherited.
Categorical and hierarchical approaches usually involve different strategies for defining and naming attributes.
When using categorical values, you must ensure that each and every user has the attribute defined, and you
must handle the case when it is accidentally undefined, such as a new user. When using hierarchical values, you
define attributes with the same name at different levels, such that each user may have a custom value, but then
the server level provides a default value for all users. Each strategy is useful for different applications,
depending on your needs to access and protect data. However, both strategies can co-exist and be used by at the
same time by different resources, as long as the names of attributes used in each strategy or each resource are
kept distinct.

2.3.3

Attribute Encryption
By default, an attribute and its value can be known to administrators throughout the server.
JasperReports Server provides two mechanisms to protect sensitive attributes:
•

Attribute encryption – Prevents the attribute value from ever being seen. Does not prevent the attribute
name from being seen or the value from being redefined at a lower level. When an attribute value is
encrypted, the value stored internally is encrypted and never decrypted in the user interface. The server
decrypts the attribute only when it is referenced by one of the features of the server. The decrypted value is
then used for internal operations and never visible to the user.
For example, an encrypted attribute could store the password for a database. Once typed in and saved, the
UI displays *** as the value of the attribute. When a report uses that database, the server decrypts the
password and sends it as part of the database protocol, so the user and the admin never see the password.
Encrypted attributes are similar to user passwords in the server. Administrators can change the encrypted
value to a new value, but they can never view the current value.

•

Attribute permissions – Prevents the attribute from being visible or redefined at a lower level. Attribute
permissions are described in the next section.

To properly secure an attribute, you should make it encrypted so it cannot be seen and then set permissions so it
cannot be overridden.

2.3.4

Attribute Permissions
Attribute permissions were designed to work with multiple organizations in commercial editions of
JasperReports Server. The feature has limited use in the Community Project edition.

The attribute permissions and their effects are as follows:
•

Administer – This is the default permission.
Inthe Community Project edition, use this permission unless you want to disable an attribute with the noaccess permission.

•

Read Only – Inthe Community Project edition, this permission has no effect.

TIBCO Software Inc.

JasperReports Server Community Project Administrator Guide

•
•

2.3.5

Execute Only – Inthe Community Project edition, this permission has no effect.
No Access – The attribute is disabled and its value cannot be referenced. When referenced, an attribute with
no-access permission returns an error.

Managing Server Attributes
If a given attribute name is not defined on a user, it can have a value at the server level to act as a default value.
Server-level attributes may also be used as parameters in data source definitions. For example, the same data
source may be imported to several servers, such as test and production servers, but a server-level attribute with
the same name on each server makes the data source connect to a different database.
To view, create, modify, or delete server-level attributes:
1. Log in as an administrator (jasperadmin).
2.

Select Manage > Server Settings and choose Server Attributes from the left-hand panel.
Each server level attribute is listed with its value, encrypted status, and permission. Holding the pointer
over an attribute name shows the description associated with the attribute. When an attribute value is
encrypted, its value is shown as *** symbols.

Figure 2-7 Managing Attributes at the Server Level
3.

To create a new server-level attribute, click Add new attribute. Enter the attribute name and value, as well
as an optional description. If desired, set the permission from the drop-down list and select the Encrypt
check box. Click OK to close the dialog and then click Save to submit the new attribute.

TIBCO Software Inc.

Chapter 2 User and Role Management

Figure 2-8 Adding a Server Attribute

2.3.6

To modify an attribute, click the edit icon
. In the edit dialog, modify the desired fields. Click OK to
close the dialog and then click Save to modify the attribute.
You can also modify the attribute's permission and encryption by using the drop down and check box in its
table row. After confirming any changes, click Save to make them take effect.
When modifying an attribute, be aware of the following:
• Changing the name of an attribute is equivalent to deleting the original attribute and adding a new
attribute with the same value. Because this may impact features that reference the attribute, you are
asked to confirm the name change.
• Be aware that changing the encryption or permission of an attribute can impact the visibility of an
attribute and the features that might rely on referencing its value. Again, you are asked to confirm the
change.
• Removing encryption does not decrypt an encrypted attribute. To safeguard encrypted values, removing
the encryption on an attribute also erases its value. You should give the attribute a new value by
clicking the edit icon.

To delete an attribute at the server level, click the delete icon
in the attribute row and confirm the
operation. Because this may impact features that reference attributes, you are asked to confirm the deletion.
Click Save to make the deletion take effect.

Managing User Attributes
Attributes on users can provided additional information about a user and can restrict access to data OLAP
schemas. Users may also have hierarchical attribute values inherited from server-level attributes. Attributes on
users do not have permissions.
Users never see the attributes defined on their user profile; only administrators can view and set user attributes.
To view, create, modify, or delete user-level attributes:
1. Log in as an administrator (jasperadmin).

TIBCO Software Inc.

JasperReports Server Community Project Administrator Guide

2.
3.

Click Manage > Users.
Select the user in the Users panel. The properties panel includes a table of all attributes for the user, both
locally defined and inherited from the server level.

Figure 2-9 Viewing Attributes on the Manage Users Page
4.

To create, modify, or delete the attributes on a user, click Edit in the right-hand column, then select the
Attributes tab.

Figure 2-10 Editing User Attributes
5.

You can filter attributes in the list to include only the inherited attributes or only the locally defined (not
inherited) ones.

TIBCO Software Inc.

Chapter 2 User and Role Management

To create a new user attribute, click Add new attribute. Enter the attribute name and value, as well as an
optional description. If the attribute value should not be visible to other administrators, select the Encrypt
check box. Click OK to close the dialog and then click Save to submit the new attribute.

Figure 2-11 Adding a User Attribute
7.

To modify an attribute, click the edit icon
. In the edit dialog, modify the desired fields. Click OK to
close the dialog and then click Save to modify the attribute.
You can also modify the attribute's encryption by using the and check box in its table row. After
confirming any changes, click Save to make them take effect.
When modifying a user attribute, be aware of the following:
• Inherited attributes belong to the server level and are shown at the user level to display the hierarchical
attribute values. Any modification to an inherited attribute actually creates a local attribute definition
with the modified parameters. In the hierarchy of attributes, the new attribute takes precedence over the
previously inherited attribute.
• Changing the name of a locally defined attribute is equivalent to deleting the original attribute and
adding a new attribute with the same value. Because this may impact features that reference attributes,
you are asked to confirm the name change.
• Removing encryption does not decrypt an encrypted attribute. To safeguard encrypted values, removing
the encryption on an attribute also erases its value. Click the edit icon to give the attribute a new
value.

To delete a user attribute, click the delete icon
in the attribute row and confirm the operation. Because
this may impact features that reference attributes, you are asked to confirm the deletion. Click Save to make
the deletion take effect.
When deleting a user attribute, be aware of the following:
• Upon deletion, some attributes remain in the list as inherited attributes. This indicates that the local
definition of the attribute was deleted, but another attribute with the same name exists at the server
level.

TIBCO Software Inc.

JasperReports Server Community Project Administrator Guide

•

You cannot delete an inherited attribute because it belongs to the server level. To remove an inherited
attribute, you must delete it or set its permission to No Access at the server level.

TIBCO Software Inc.

CHAPTER 3

REPOSITORY ADMINISTRATION

JasperReports Server provides a powerful and flexible environment for deploying and running JasperReports.
The repository stores all the resources used to run and create reports, including data source definitions, JRXML
files, datatypes, and helper files such as images. Administrators create the folders and resources so users can
create, run, and save the reports they need. For administrators who want to customize the user interface, the
repository also holds the CSS and image files that define themes.
The repository is structured as a hierarchy of folders. The JasperReports Server web interface enables you to
browse the repository's resources, manage its folder structure, and secure its contents. This chapter covers the
basic tasks of administering the repository, including:
•
•
•

Creating folders and organizing repository objects.
Managing references to data sources, images, fonts, and other resources upon which reports rely.
Controlling access to resources in the repository through roles and object-level permissions.

Further information about the repository is available in the following sections:
•
•
•

1.1, “Overview of the Repository,” on page 10
Chapter 5, “Other Resources in the Repository,” on page 75
Chapter 6, “Themes,” on page 99

You can also access the repository using the web services (see the JasperReports Server REST API Reference)
and APIs (see the JasperReports Server Ultimate Guide).
This chapter contains the following sections:
•
•
•
•

3.1

Resource Types
JasperReport Structure
Managing Folders and Resources
Repository Permissions

Resource Types
Some resources are created interactively, others are uploaded from files. Many of these resource types are used to
upload or define the components of reports. The following tables list the resource types that users and
administrators can create in the repository:

TIBCO Software Inc.

JasperReports Server Community Project Administrator Guide

Table 3-1 Resource Types in the Repository
Resource Type

Description

JasperReport
(JRXML report)

A JasperReport combines a JRXML file, a data source, and optional components
such as input controls. Depending on the use case, both users and administrators
create JasperReports in the server. For more information, see 3.2, “JasperReport
Structure,” on page 33. Procedures for adding reports to the server are described
in the JasperReports Server User Guide.

Content resource

Report output of any format, either from running a report in the background or from
scheduling a report. A content resource is a simple file that the repository allows
users to view or download.

Data source

A connection that points to a database or other data store. Data sources define
where data is stored for reporting. There are several types of data sources, based
on the type of connection or location of the data: JDBC, JNDI, and several others.
Only administrators may create data sources. For more information, see Chapter 4,
“Data Sources,” on page 47.

Query

A database query string, for example in SQL. The JRXML doesn't necessarily
include the query, in which case, you must define a query resource for use in the
JasperReport.

Input Control

A complex type that specifies the values users can input for a report and how the
input field appears when running the report, for example radio buttons or check
boxes. Input controls depend on datatypes or lists of values to specify the format of
the input.

Datatype

A basic resource that defines the format for input values, for example text, number,
or date. A datatype may also specify a valid range for the input value.

List of Values

A basic resource that defines a list of arbitrary labels for input. Each label is
associated with a value that can correspond to your data. For example, the Month
Names List in the sample data associates the name of each month with a value 1 to
12.

File

A resource that stores a file in the repository, usually as part of a report, such as a
JRXML file or image logo. The supported file formats are listed in Table 5-3, “File
Resource Types,” on page 93.

Administrators and users can also manage OLAP resources in the repository, if their license supports Jaspersoft
OLAP. For more information about OLAP and Mondrian resources, see the Jaspersoft OLAP User Guide.

TIBCO Software Inc.

Chapter 3 Repository Administration

Table 3-2 Resource Types for OLAP

3.2

Resource Type

Description

Mondrian XML/A Source

A server-side XMLA source definition of a remote client-side XML/A connection.

OLAP Client Connection

Specifies how to retrieve data for an OLAP view. An OLAP client connection is
either a direct Java connection (Mondrian connection) or an XML-based API
connection
(XML/A connection).

OLAP View

If you implement Jaspersoft OLAP, a view of multidimensional data based on an
OLAP client connection and an MDX query. Like JasperReports, OLAP Views are
collections of individual resources that define how to access and present the data.

JasperReport Structure
The repository resource that aggregates all information needed to run a report is called a JasperReport. A
JasperReport is based on a JRXML file that conforms to the JasperReports Library that the server uses to render
reports.
A JasperReport is a complex resource composed of other resources:
•
•
•
•
•
•

The main JRXML file that defines the report
A data source that supplies data for the report.
A query if none is specified in the main JRXML.
• The query may specify its own data source, which overrides the data source defined in the report.
Input controls for parameters that users may enter before running the report. Input controls are composed of
either a datatype definition or a list of values.
Any additional file resources, such as images, fonts, and resource bundles referenced by the report template.
If the report includes subreports, the JRXML files for the subreports.

The collection of all the resources referenced in a JasperReport is sometimes called a report unit. End users
usually see and interact with a JasperReport as a single resource in the repository, but report creators must define
all of the component resources.

3.2.1

Referencing Resources in the Repository
There are several ways to define and reference all the resources in a JasperReport.
In environments without JasperReports Server, reports are stored in the file system, and shared resources are
usually stored on a network drive accessible to all developers and users. This solution is sometimes impractical,
as you can't always add such resources to the classpath, and the use of absolute paths has its own limitations.
Also, storing the resources in the file system discourages their reuse. Developers may invest time recreating
resources because they don't know they exist.
By storing resources in the repository, JasperReports Server makes it easy and reliable to share resources such as
images, style templates, and subreports among reports. The repository mimics a folder and file structure, so
references to external files can be handled as references to external resources in the repository.

TIBCO Software Inc.

JasperReports Server Community Project Administrator Guide

The repo:syntax used in some previous versions is no longer required; regular file paths are recognized and
managed within the repository.
When you upload your JRXML to the repository, your file references become valid repository references, and
you can store all your resources in well-known locations in the repository. This simplifies the process of
uploading your reports, because you don't have to upload the resources each time. Also, you can manage these
resources either through Jaspersoft Studio, the JasperReports Server user interface, or the server's REST API. For
example, when you update a logo image, all reports that reference that resource display the new logo.

3.2.2

Absolute References
Absolute references are the URIs of resources in the JRXML of a report. A path may refer to the file system
where the JRXML was created, but when uploaded to the server, it refers to folders in the repository.
The path must start with one of the following:
/ to represent the root of the repository. For example, /images/logo is the path to a resource in the

/images folder.
../ to represent the folder where the JasperReport is uploaded. For example, ../myLogo is the path to a

resource in the same folder as the JasperReport.
As with a file system path, the repository path is composed of the resource ID of every parent folder, ending
with the ID of the resource. Jaspersoft Studio supports absolute references by allowing you to drag resources
from the repository tree view into the design area.
When uploading the JRXML with absolute resource references as part of a JasperReport in the server, you need
to ensure only that the resource with the given path exists in the repository before running the report. When the
report runs, the server locates the resource in the repository and uses it to render the report.
Because file resources such as images, fonts, and JARs are the only resources for which you can create references
directly in JRXML, they are the only resources for which you can create absolute references.
One disadvantage of absolute references is that JasperReports Server does not maintain the dependency between
the JRXML and the absolute reference. When uploading the JRXML, there is no warning if the resource does
not exist, and the server allows you to delete the resource from the repository even if it is still being referenced.
If the resource is not available, running the report fails with an error.

3.2.3

Local Resources and External References
JasperReports Server provides more flexibility and power when you use indirect references instead of absolute
references. Indirect references are placeholder names that must be manually linked to the resource when
uploading the JasperReport. The syntax for an indirect reference contains only a resource placeholder name, for
example:
logoImage

When you upload a JRXML with an indirect reference, the server prompts you to provide the resource. You
have two options:
•

•

Create a new resource, in this case by uploading an image that becomes part of the JasperReport. This is
called a local resource. You can't access this resource from elsewhere in the repository, it exists only within
the JasperReport.
Select a resource from the repository. This is called an external reference because it is external to the
JasperReport. Any number of reports can link to the same external resource, and the resource can be
managed independently of them.

TIBCO Software Inc.

Chapter 3 Repository Administration

While indirect references require slightly more work than absolute references in the JRXML, the server manages
the dependency. Local resources exist as part of a JasperReport, and external references cannot be deleted until
they are no longer referenced.
In cases where you don't want to reference existing resources, local resources allow reports to be highly
customized and self-contained. A local resource defined inside the JasperReport has all the same properties as a
repository resource, but it's not accessible in the repository. Users must edit the JasperReport to access any
resources it defines locally.
Indirect references are used implicitly in several other cases when you define a JasperReport:
•
•
•
•

The main JRXML itself is either a local resource created by uploading a file or an external reference to an
existing JRXML file resource in the repository.
Every report must have a data source, and JasperReports Server gives you the option to either create a new
local resource or use an external reference to an existing data source.
Every report must also have a query that matches its data source. You may choose to create a local query
resource or use an external reference to an existing query.
Parameters in a report are implicitly handled as an indirect reference to an input control. For every parameter
named in your main JRXML, you must define an input control either as a local resource or external
reference.

Every level of indirect referencing is independent of the other. For example, when creating a JasperReport, you
may choose to create an input control as a local resource, but that input control may have an external reference
to its datatype. The server still manages the dependency between the local input control and the datatype
resource in the repository.
Local resources and external references are used by several resources, for example when creating input controls,
query resources, Domains, and OLAP resources.

3.2.4

References in Subreports
A subreport is a subordinate JRXML file within a JasperReport. As with all other resources referenced by the
main JRXML, the subreport JRXML file may be specified by an absolute reference, a local resource or an
external reference.
As a JRXML file, a subreport can reference other resources of its own. However, the subreport is run as part of
the main JRXML, and any references in the subreport are interpreted relative to the JasperReport resource
(represented by the main JRXML) and the context in which the JasperReport is being run.

3.2.5

Data Snapshots
Report resources can also store a snapshot of the report data. A snapshot is a copy of the data that the query
returns when the data is refreshed. This data snapshot is an internal structure not visible or accessible from the
repository. However, when data snapshots are enabled, a data snapshot is stored in the repository with each
report. When users open a report, the report viewer retrieves and displays the data from the snapshot. Users then
have the option of refreshing the data in the report viewer, and if they have permissions, saving the data
snapshot back into the report resource.
For more information about interacting with data snapshots, see the JasperReports Server User Guide. To enable
snapshots, see 8.4, “Enabling Data Snapshots,” on page 133.

TIBCO Software Inc.

JasperReports Server Community Project Administrator Guide

3.3

Managing Folders and Resources
Administrators and users with the proper permissions can create, modify, move, and delete folders and resources
in the repository. The specific roles and permissions of the user determine the actions available. For the
definition of the permissions on folders and resources, see 3.4, “Repository Permissions,” on page 41.
One responsibility of an administrator is to set up an environment for users to create and save dashboards, Ad
Hoc views, and reports. That usually means creating a folder structure where users have write permission. Users
with write permission can also create their own sub-folders to store their reports and dashboards.
Only administrators can create data sources in the repository. So, although users with write permission can
upload JRXML files and define resources, they can't run their reports without data sources. For this reason, we
recommend that administrators create data sources and other shared resources in the repository. For example,
uploading one shared logo file and keeping it up to date is better than many users uploading and maintaining
their own separate logo files.

3.3.1

Resource IDs
Each resource, including each folder, has an ID, a name, and an optional description:
•
•
•

The ID is used internally to reference a resource. The ID must be unique within its folder, but may exist in
multiple folders.
The resource name is displayed in the repository.
The description, if defined, appears in the repository and in tooltips.

As in a file system, the IDs of nested folders define the path to a resource. For example, the path to a report
might be: /reports/samples/Freight.
To view the name and resource ID of a resource, Right click the folder's name or the resource in the repository
or search results and select Properties... from the context menu.

Figure 3-1 Resource Properties Dialog for a Writable Resource

TIBCO Software Inc.

Chapter 3 Repository Administration

If you have write or administer permission as shown in the figure, you can also edit the name and description of
the resource. For some operations such as export, you need the path, also called repository URI, which you can
copy from this dialog.

3.3.2

Creating Folders
Any user with write permission on a folder can create new sub-folders.
To create a folder:
1. Log on as a user who has write permission to the parent folder.
2.

Select View > Repository and locate the parent folder in the Folders panel.

Right-click the parent folder and select Add Folder from the context menu. The Add Folder dialog
appears.

Figure 3-2 Add Folder Dialog
4.

Enter the folder name and, optionally, a description, then click Add.
The folder is created in the repository. The name appears in the hierarchy of folders. The description is
visible only when viewing the properties of the folder, as shown in Figure 3-1.
New folders and their future contents inherit the permissions of their parent folders. Users with
Administrator permissions can change permissions folders, as described in 3.4.6, “Setting Permissions,” on
page 44.

3.3.3

Adding Resources
Each resource has different requirements, for example some are created from uploaded files, others are created by
defining values in a wizard. The procedures for adding each type are available in the documentation below:
•
•
•
•

JasperReports are covered in the JasperReports Server User Guide.
Mondrian and OLAP resources are covered in the Jaspersoft OLAP User Guide.
Data sources are explained in the chapter Chapter 4, “Data Sources,” on page 47.
Queries, data types, lists of values, input controls, and file resources are explained in the chapter Chapter 5,
“Other Resources in the Repository,” on page 75

TIBCO Software Inc.

JasperReports Server Community Project Administrator Guide

Most resources are created through the Add Resource menu item on the context menu for folders in the
repository. In the following figure, you can see the full menu and submenu with all the resources administrators
can create:

Figure 3-3 Add Resource Context Menu Expanded
For every resource you create, you must specify a name and resource ID for referencing the resource in the
repository. Each wizard also has one or more pages for specifying the values and controls specific to the
resource.
New resources inherit the permissions of the folder in which they are created. Administrators can change
the permissions on the new resource, as described in section 3.4.6, “Setting Permissions,” on page 44.

3.3.4

Renaming Folders and Resources
Any user with write permission on a folder or resource can change its name and description.
To rename a folder or resource:
1. Log on as a user who has write permission for the folder or resource.

In the repository, browse or search for the resource. For renaming folders, select View > Repository and
locate the folder.

Right-click the object and select Properties... from the context menu. The Properties dialog appears.

TIBCO Software Inc.

Chapter 3 Repository Administration

Figure 3-4 Properties Dialog for a Report Resource
You can change the folder or resource's name and description, but not the ID; the ID is permanent once the
resource is created.
4.

3.3.5

Click Submit to save your changes.

Copying and Moving
The repository interface lets any user with the proper permission copy or move both resources and folders.
Copying requires read permission on the source, moving requires delete permission on the source, and both
require write permission on the destination folder.
You can drag-and-drop the objects, or you can copy-paste or cut-and-paste them from their context menus.
Folders must be moved one at a time, but multiple resources from the same folder can be copied or moved
together.
Copying and moving actions are not possible on the search interface, only on the repository interface showing
the list of folders. Currently, it's not possible to create a copy of a resource in the same folder.
The moved objects inherit their permissions from the destination folder; they do not keep the permissions
they had before the move. If you want the objects to have other permissions, you can set new permissions
after the move (see 3.4, “Repository Permissions,” on page 41).

To copy or moving folders and resources:
1. Log on as a user who has the required permissions for the folder or resource.
2.

Click View > Repository, and expand the folders to display the object to be copied or moved.

Right-click the resource and select Copy or Cut (delete permission is required to cut a resource).
You can select multiple resources with Control-click or Shift-click, but only a single folder.

TIBCO Software Inc.

JasperReports Server Community Project Administrator Guide

Right-click the destination folder and select Paste in the context menu (write permission is required on the
destination folder).
Alternatively, you can drag to move the selected resource or folder to the destination folder. To copy, press
and hold the Ctrl key then click and drag. When dragging resources, the destination folder is highlighted in
blue if you have write permission to it.

3.3.6

Editing Resources
The procedure for editing a resource depends on the resource type. All of the dialogs are available by rightclicking on the resource in the repository and selecting the proper action from the context menu. In nearly all
cases, the dialog for editing is the same one that was used to create the resource.
Table 3-3 Editing Resources
Resource Type

How to Edit

JasperReport

To change the layout of an interactive report, users may Run the report, then
change the column filters or sorting. Users may save the report, either by
overwriting the original or as a new copy, depending on their permissions.
To change the definition of a report, right-click the report resource and select Edit.
Then you can change the data source, input controls, or file resources referenced
in the JasperReport. For more information, see 3.2, “JasperReport Structure,” on
page 33.

Content Resource

A content resource is report output that is stored as a file stored in the repository.
These files cannot be edited, only downloaded or deleted.

Data Source

Administrators only: right-click the data source, then select Edit from the context
menu. For more information, see Chapter 4, “Data Sources,” on page 47.

Query

Right-click the resource, then select Edit from the context menu on these
resources. You edit these resources in the same dialog you used to create them.
For more information, see Chapter 5, “Other Resources in the Repository,” on
page 75.

Input Control
Datatype
List of Values
File

When editing a resource, you have several limitations:
•
•
•

You can't change a resource's ID. If you need to change an ID, you have to create a new resource and delete
the old one.
You can't change the location of a resource. To change the location of the resource, see 3.3.5, “Copying
and Moving,” on page 39.
For file resources, you can't see the name of the file that was uploaded, nor in most cases download and
view the contents of the file. Your only option is to upload a new file to replace the old one.

TIBCO Software Inc.

Chapter 3 Repository Administration

3.3.7

Deleting Folders and Resources
Users with delete permission on folders or resources can delete those objects from the repository. To delete a
folder, you also need delete permissions on all the resources and folders in that folder. Folders must be deleted
one at a time, but multiple resources can be deleted together.
You can't undo a delete.

The repository won't allow you to delete resources currently referenced by other resources. For example, an
input type used by a report cannot be deleted as long as the report still references them.
To find the resources that reference the one you want to delete, you need to look at each report that you suspect
of referencing it. When you edit the definition of a JasperReport, you can see the resources it references. Then
you can either remove the reference from the resource or delete the entire resource containing the reference.
To delete a folder or resource:
1. Log on as a user who has delete permission for the folder or resource.
2.

In the repository, browse or search for the object to be deleted.

Right-click the object and click Delete in the context menu.
In the repository view, you can select multiple resources and click Delete in the tool bar or in the context
menu. In the list of folders, you can delete only one folder at a time, but all contents of that folder will be
deleted. In the search results, you can select multiple resources and right-click to select Delete in the
context menu.

3.4

Repository Permissions
Permissions on folders and resources determine what users see in the repository and what actions they're allowed
to perform. In the following table, the actions granted by each permission include all of the actions granted by
permissions above it, except for the No Access permission. The actions granted by each permission strictly
exclude all of the actions granted by permissions below it.
Permission

Actions Granted on Repository Folders and Resources

No Access

Users can never see or access the folder or resource, either directly in the
repository or indirectly when running a report or OLAP view. If one of these
reference a resource that is set to no-access, the user will see an error when trying
to run it.

Execute Only

Users can never see the folder or resource in the repository, but they can run
reports or OLAP views that access them. Typically, data sources are execute-only
so that users may run reports but not see database connection details.

TIBCO Software Inc.

JasperReports Server Community Project Administrator Guide

Permission

Actions Granted on Repository Folders and Resources

Read Only

•
•
•
•
•
•
•

See the folder or resource in any server
See the properties of a folder or a resource
Copy a folder and all of its readable contents
Copy resources individually or in bulk
View (run) a report or OLAP view
Run a report in the background
Schedule a report to run later

Read + Delete

•
•
•
•

Cut (move) a folder and all of its contents
Delete a folder and all of its contents
Cut (move) resources individually or in bulk
Delete resources individually or in bulk

Read + Write

•
•

Copy resources to a folder with this permission
Edit and modify resources

Read + Write + Delete

•
•
•
•
•
•
•

Add a subfolder
Add (create) a resource in a folder
Paste into a folder (copy or cut)
Save the output of a scheduled report in a folder
Rename a folder or resource and change its description string
Add a JasperReport resource to the repository (upload a JRXML)
Edit the definition of a JasperReport resource in the repository (replace the
JRXML)

Administer

•

Set the permissions (by role and by user) on a folder or resource. This
effectively delegates certain repository administration tasks.

Administer and ROLE_
ADMINISTRATOR

•

Add (create) a Domain or a data source

Permissions apply when browsing or searching the repository and when using any dialog that accesses the
repository, like browsing folders to save a report. Note that:
•
•
•
•
•

Copying does not preserve the permissions on an object. Users may copy a read-only object, paste it into a
read-write folder, then edit the object. For more details, see 3.3.5, “Copying and Moving,” on page 39.
Copying and cutting (moving) actions can be completed only by a user with Read + Write + Delete access
to the folder in which the object is pasted. For more details, see 3.3.5, “Copying and Moving,” on page 39.
Cutting, deleting, and setting permissions on folders is allowed only if the user has the same permission on
all folder contents.
Cutting and deleting resources in bulk is allowed only if the user has at least Read + Delete permission on
all selected resources.
Deleting a resource is allowed only if no other resources rely on it. For more details, see 3.3.7, “Deleting
Folders and Resources,” on page 41

TIBCO Software Inc.

Chapter 3 Repository Administration

3.4.1

Inheriting Permissions
According to the permission architecture, there may be a permission setting for every user and role on every
folder and resource in the repository. To simplify the definition of permissions, JasperReports Server supports the
inheritance of permissions from the parent folder to a folder or resource. If no permission is explicitly defined for
a user or role on a given folder or resource, the user or role has the same access permission that is defined on the
parent folder. When a permission is defined explicitly, that permission is enforced, regardless of those on the
parent folder.
Using permissions, you can manage large hierarchies of content and keep them secure. When you set a
permission explicitly, that permission for a given user or role is inherited recursively by all of the folder's
contents and subfolders, unless they have an explicit definition of their own.

3.4.2

Cumulative Permissions
Because permissions can be assigned to both users and roles, a user belonging to one or more roles may have
multiple permissions defined or inherited on any given folder or resource. In fact, every permission must be
defined on the root, even if it has the default value of No Access, and therefore every role- and user-based
permission on every folder and resource has a setting through inheritance. So, for every folder or resource, every
user has their own user-based permission and the permission assigned to the ROLE_USER.
How does JasperReports Server determine the effective permission from the many that apply? Permissions in the
server are strictly cumulative, meaning that the least restrictive among the set of all permission applies. Even if a
more restrictive permission, such as No Access, is set explicitly, the less restrictive permission such as ReadOnly applies, regardless of whether it is inherited or set explicitly. This is why all default permissions at the
root are set to No Access initially.

3.4.3

Administrator Permissions
The JasperReports Server authorization architecture distinguishes between administrators and all other users.
Administrators are defined as users with ROLE_ADMINISTRATOR. By design, administrators with the ROLE_
ADMINISTRATOR always have irrevocable Administer access to the entire repository. The administrator
cannot modify the permissions for ROLE_ADMINISTRATOR, to prevent being locked out or unable to
administer some resource. Therefore, the administrator can set permissions for all other users, on any folder or
resource.

3.4.4

Execute-Only Permission
As in file systems, execute-only permission in JasperReports Server allows running reports and OLAP views to
access a resource, but keeps the resource from appearing in the repository.
Execute-only permission applies to folders as well, keeping them from appearing in the folder tree when users
browse the repository, yet still allowing the resources they contain to inherit the execute-only permission. This
is useful for hiding folders and resources such as data sources that only administrators and data analyst roles
need to access in the repository. However, if your execute-only folder contains read-only resources, those
resource are hidden when browsing folders but can be found with a repository search.
As with all other permissions, execute-only permission is either role-based or user-based, so only certain users
can access a resource from a running report.

TIBCO Software Inc.

JasperReports Server Community Project Administrator Guide

If you have data or sensitive content in a resource, always set No Access permission for users or roles
that must not be able to access it.
Hiding a resource with execute-only permission does not protect against access, because malicious
users who find the resource ID may be able to create a report, dashboard, or OLAP view that extracts the
sensitive content.

3.4.5

Default User Permissions
For all non-administrator users, the default permission at the root is No Access and any permissions must be
explicitly defined. In practice, the default installation of the repository contains sample data with a mix of no
access, execute only, read only, and read-write permissions that allow the sample users to access folders and
resources. The sample permissions demonstrate a common approach to permissions, allowing users to see the
resources they can access and hiding the ones they can't, while administrators have full access.
We recommend you familiarize yourself with permissions by viewing and setting permissions in the sample
data, as described in the following section.

3.4.6

Setting Permissions
Administrators can assign permissions to access any folder or resource throughout the repository. Users with the
Administer permission on a folder can assign permissions to that folder and any contents that inherit the
permission. Users granted Administer permission to a resource can set the permissions only on that specific
resource.
To set permissions on a folder or resource in the repository:
1. Log in as a user with administrator privileges.
2.

Browse or search the repository for the folder or resource.

Right-click the object and select Permissions... from the context menu:

The Permissions dialog opens showing the permissions in effect for the selected object. By default, it first
shows the permissions given to roles. Permissions that are inherited from the object's parent are indicated by
asterisks (*).

TIBCO Software Inc.

Chapter 3 Repository Administration

Figure 3-5 Permissions Dialog Showing Permissions by Role
In the previous figure, you can see the default role-based permissions on the sample Data Source folder.
Regular users have execute only permission so they do not see this folder, but the reports they run can
access its contents. Administrators are prevented from changing the permission for their administrator role or
user name, to prevent them from removing their ability to set permissions.
4.

In the dialog, click User to view the permissions assigned to specific users. Click Role when viewing user
permissions to toggle back.

For each user or role, you can select a new permission from the drop-down.
In the next figure, you can see the default user permissions on this folder. In the default installation, all
permissions are defined by role; so, all user permissions are No Access inherited from the root. The figure
shows a read-only permission being granted to the sample end user. This enables joeuser to see but not
modify the Data Sources folder and its contents. For all other end users, the folder is still execute-only due
to the settings in Figure 3-5.

Figure 3-6 Permissions Dialog Showing Permissions by User

TIBCO Software Inc.

JasperReports Server Community Project Administrator Guide

Click Apply to apply your changes. If you toggle between user and role permissions, first apply any
changes you made.

Click OK to save your changes and close the permissions dialog when you're finished.
You can open several permissions dialogs for different resources or folders at the same time while
navigating the repository. This helps when trying to set permissions uniformly across several folders.
There are two special cases when setting permissions:

3.4.7

•

If a resource inherits a permission, for example Read-Only, you cannot set the permission to the same
value, at least not directly. You need to temporarily change the permission level on the parent folder,
then set the explicit permission, then set the parent folder's permission back to the original value.
When a resource and its parent folder have been set to the same permission in this way, the
permission dialog still shows the asterisk as if the permission were inherited. But if the parent is later
given a different permission, for example Read-Write, the resource retains its explicit Read-Only
permission instead of inheriting Read-Write.

•

To reset the permission level so that it once more inherits from its parent folder, select a different
permissions level and click Apply, then select the permission with the asterisk and click Apply again.

Testing User Permissions
Once you have configured users, roles and permissions, we recommend that you test the permissions granted to
a few representative users. We also recommend testing whenever you add new users, roles, and resources or
make any major modifications to your access control configuration.
To test user permissions:
1. Log in as an administrator.
2.
3.

Select Manage > Users.
Browse or search for the user whose permissions you are testing.

In the Users panel, select the user.

In the Properties panel, click Login as User. The selected user's Home page appears. The login information
in the upper-right corner shows that you are logged in as that user.

Verify that the expected folders and resources are available in the repository. Make a note of any objects
that should be there but are not, and any that should be hidden but are displayed.

7.
8.

When you have verified the user's permissions, click Log Outto exit that user's account.
To change the user's permissions, edit the permissions in the repository and modify the user or role
definitions.

Continue testing until the user's permissions are satisfactory.

10. Repeat these steps with several representative users to ensure that your access control is properly
configured. An untested access control configuration can't secure your data adequately.

TIBCO Software Inc.

CHAPTER 4

DATA SOURCES

A data source is a resource in the repository that specifies how and where to obtain the data displayed by
reports and OLAP views. Administrators must define data sources before uploading reports that rely on them.
Typically, a data source specifies the URI of the database server and the details you need to access it, such as a
user name and password.
JasperReports Server provides data source types for relational databases, most flavors of big data, and for
specialized data such as Amazon Web Services and JavaBean data. Virtual data sources allow you to combine
several data sources into one.
JasperReports Server can access any relational database that supports the SQL query language through the JDBC
(Java DataBase Connectivity) API. In this case, you can configure two types of data sources in the repository:
•

•

JDBC data source – Establishes a direct connection to the database server using its JDBC driver. After
installation, JasperReports Server includes JDBC drivers to access MySQL and PostgreSQL. If you want to
install drivers for other databases, or if you want to use alternate drivers, the administrator can upload and
manage JDBC drivers through the UI. With JDBC data sources, JasperReports Server configures and
manages the connections to the database. By default, the maximum number of simultaneous connections for
each data source is 20.
JNDI data source – Relies on the JNDI (Java Naming and Directory Interface) service of your application
server to access a database connection. You must first configure your application server to install its JDBC
drivers and configure its database connections. With JNDI data sources, the configuration of the application
server determines the number of shared connections. Note that the application server connects to the
database using JDBC, meaning that JNDI data sources are available for all databases that support JDBC.

Big data stores that have custom data sources:
•

•

Cassandra – This data source is different from the community-contributed data source for Cassandra. It
supports the Cassandra Query Language CQL 3. JasperReports Server also provides a JDBC driver for
Cassandra data sources.
MongoDB – This custom data source for MongoDB supports Jaspersoft's own MongoDB Query Language.
A MongoDB JDBC driver is also available.

JasperReports Server also supports some specialized data sources:
•
•
•
•

Amazon Web Services (AWS) data source – Accesses data stored in your AWS data store using
JasperReports Server, either on-premises or in the cloud.
Microsoft Azure SQL data source - Allows you to access data stored in your Azure SQL Server database.
File data source – Allows you to generate reports based on data in XML and JSON format.
Bean data source – Allows you to access data encapsulated in JavaBeans.

TIBCO Software Inc.

JasperReports Server Community Project Administrator Guide

In the case of analysis data, JasperReports Server supports OLAP data sources (such as Mondrian and XML/A
connections). For information about analysis data sources, refer to the Jaspersoft OLAP Ultimate Guide.
You can extend JasperReports Server to support any custom data source. Custom data sources consist of
Java implementation classes, a message catalog, and a Spring bean definition. For more information
about custom data sources, see the JasperReports Server Ultimate Guide.

This chapter contains the following sections:
•
•
•
•
•
•
•
•
•
•

4.1

Attributes in Data Source Definitions
JDBC Data Sources
Managing JDBC Drivers
JNDI Data Sources
AWS Data Sources
Azure SQL Data Sources
Cassandra Data Sources
MongoDB Data Sources
File Data Sources
Bean Data Sources

Attributes in Data Source Definitions
You have two options for defining the parameters of a data source, such as the host and port number:
•
•

Define the parameters statically, so that they are the same for every user.
Have the server derive these parameters at run time based on attributes you provide.

Attributes can be used to derive all data source parameters that are not selected from drop down lists. For
instructions on how to create attributes, see 2.3, “Managing Attributes,” on page 24.
When referring to an attribute in a data source definition, you can specify the attribute categorically or
hierarchically:
•

•

Categorical reference – If you specify a category for the attribute value, the server attempts to find that
particular value of the attribute. If the attribute is not defined where specified, the reports using this data
source will fail with an error. You can specify these attribute categories:
• User – In the attributes defined on the logged-in user.
• Server – In the attributes defined at the server-level.
Hierarchical reference – If you don't specify a category for the attribute, the server searches attributes
hierarchically and uses the value of the first attribute it finds with the given name. This search starts with
the logged in user, then proceeds to the server level. If the specified attribute is not found in either of these,
the reports using this data source will fail with an error.

The following figure is an example of attributes used to define data source parameters.

TIBCO Software Inc.

Chapter 4 Data Sources

Figure 4-1 Using Attributes for Data Source Parameters
In the example above, the following data source parameters are specified by attributes:
•
•
•
•
•

•

{attribute('host','User')} - Host will be derived categorically from the logged-in user's attributes,

because the "User" category is specified.
{attribute('port','Server')} - Port will be derived from the server-level attributes.
{attribute('db','Server')} - Database name will be derived from the server-level attributes.
The URL is generated automatically from the host, port, and database fields.
{attribute('userName')} - The user name will be derived hierarchically, because no category is
specified. JasperReports Server will look for a host first in the logged in user's attributes, then in the serverlevel attributes.
{attribute('password')} - The password field can also reference an attribute, here a hierarchical
attribute.

For information about attributes on users and the server, see 2.3, “Managing Attributes,” on page 24.

TIBCO Software Inc.

JasperReports Server Community Project Administrator Guide

4.2

JDBC Data Sources
JDBC data sources are direct connections to your database managed by JasperReports Server. To create one, you
must provide the URL and credentials to access your database, along with any database-specific configuration
parameters.
JasperReports Server includes JDBC drivers for some databases. If your database is not included, or if you want
to use different JDBC drivers, the administrator must upload the appropriate JDBC driver before creating a data
source. For more information on JDBC drivers, see 4.3, “Managing JDBC Drivers,” on page 52.
To create a JDBC data source:
1. Log on as jasperadmin.
2.

Select View > Repository, right-click a folder's name, and select Add Resource > Data Source from the
context menu. If you installed the sample data, the suggested folder is Data Sources. The New Data Source
page appears.

In the Type field, select JDBC Data Source. The page refreshes to show the fields required for a JDBC
data source.

Figure 4-2 Setting the JDBC Data Source Type

Select the JDBC driver for your database. If your driver is listed as NOT INSTALLED, you must first
upload the driver as described in 4.3, “Managing JDBC Drivers,” on page 52.

Enter the hostname, port, and database name for your database. The default hostname is localhost, and the
default port is the typical port for the specified database vendor. The three fields are combined
automatically to create the JDBC URL where the server will access the database. When specifying values
for your JDBC data source:
• The JDBC URLs for some databases allow optional parameters described in A.10.4, “JDBC Database
URLs,” on page 167.
• You have the option to use attributes in the values of data source parameters. See 4.1, “Attributes in
Data Source Definitions,” on page 48.

TIBCO Software Inc.

Chapter 4 Data Sources

Fill in the database user name and password. These are the credentials the server will use to access the
database.

Figure 4-3 Entering the User Name and Password
The database user needs the privileges to run SELECT queries on the tables used in your reports.
The server blocks any DROP, INSERT, UPDATE, and DELETE SQL commands through its SQL
injection protection. In some cases, additional permissions may be required to execute stored
procedures, depending on your configuration and needs. For more information, see A.10.3,
“Database Permissions,” on page 166.

If the date-time values stored in your database do not indicate a time zone, set the Time Zone field. When
in doubt, leave the default Time Zone value (Use database setting).
When date-time values are stored in a format other than local time zone offset relative to Greenwich Mean
time (GMT), you must specify a time zone so that the server can properly convert date-time values read
from the target database. Set the Time Zone field to the correct time zone for the data in the database. The
list of time zones is configurable, as described in B.5.2, “Specifying Additional Time Zones,” on page 187.

Click Test Connection to validate the data source. If the validation fails, ensure that the values you
entered are correct and that the database is running. To diagnose JDBC connection issues, you can turn on
logging as described in the troubleshooting section A.10.1, “Logging JDBC Operations,” on page 166.

When the test is successful, click Save. The Save dialog appears.

TIBCO Software Inc.

JasperReports Server Community Project Administrator Guide

Figure 4-4 Saving the JDBC Data Source
10. Enter a name for the data source and an optional description. The Resource ID is generated from the name
you enter. If you haven't already specified a location, expand the folder tree and select the location for your
data source.
11. Click Save in the dialog. The data source appears in the repository.

4.3

Managing JDBC Drivers
To access a database from JasperReports Server using JDBC you need an appropriate driver that's accessible in
the server's classpath. These drivers are installed by default:
•
•
•
•
•
•
•

Cassandra (com.simba.cassandra.jdbc4.Driver)
Hive (tibcosoftware.jdbc.hive.HiveDriver)
MySQL (org.mariadb.jdbc.Driver)
Oracle (tibcosoftware.jdbc.oracle.OracleDriver)
PostgreSQL (org.postgresql.Driver)
Redshift (tibcosoftware.jdbc.redshift.RedshiftDriver)
Salesforce (tibcosoftware.jdbc.sforce.SForceDriver)

Drivers for other databases can be downloaded from links on the Jaspersoft community website:
http://community.jaspersoft.com/wiki/downloading-and-installing-database-drivers
The administrator (jasperadmin) can add JDBC drivers for other databases in the following ways:
•
•

During installation. For more information, see the JasperReports Server Community Project Installation
Guide.
At any time through the UI. As described in the procedure below, the administrator can add, replace, or
remove JDBC drivers through the user interface, without needing to restart the server.

To add a JDBC driver:
1. Log on as administrator (jasperadmin).

TIBCO Software Inc.

Chapter 4 Data Sources

Select View > Repository, right-click a folder's name, and select Add Resource > Data Source from the
context menu.

In the Type field, select JDBC Data Source. The page refreshes to show the fields necessary for a JDBC
data source.

The drop-down selector for the JDBC Driver field shows the available JDBC drivers and those that are not
installed.

Figure 4-5 Viewing the List of Available JDBC Drivers
5.
6.

Select the driver that has not been installed, then click Add Driver. The Select Driver dialog appears.
If you have not yet obtained the driver, click the link to Jaspersoft's community website for Downloading
and Installing Database Drivers. That page has links to the most commonly used JDBC drivers. After you
download a driver to your file system, you can return to the Select Driver dialog.

Figure 4-6 Adding a JDBC Driver
7.

In the Select Driver dialog, click Browse to locate the appropriate driver JAR file. If your driver has more
than one JAR file, click the Browse button that appears after selecting the first file.

Click Upload to install the driver and make it available immediately.

You can replace any driver that you upload with newer versions of the same driver..
To update a JDBC driver:
1. Log on as administrator (jasperadmin).
2.

Select View > Repository, right-click a folder's name, and select Add Resource > Data Source from the
context menu.

In the Type field, select JDBC Data Source. The page refreshes to show the fields necessary for a JDBC
data source.

TIBCO Software Inc.

JasperReports Server Community Project Administrator Guide

The drop-down selector for the JDBC Driver field shows the available JDBC drivers and those that are not
installed.

To update a driver that has already been installed, select it from the list, then click Select Driver. The
Select Driver dialog appears and notifies you that selecting a driver will overwrite the existing one.

Figure 4-7 Updating a JDBC Driver
6.

In the Select Driver dialog, click Browse to locate the JAR file for the new driver.

7.
8.

Click Upload to replace the existing driver and make it available immediately.
You can now use this driver to create a data source.

To remove an uploaded JDBC driver:
1. Log on as administrator (jasperadmin).
2.
3.

Select Manage > Server Settings and choose Restore Defaults from the left-hand panel.
Locate the driver you uploaded in the list of properties. The drivers with the value [SYSTEM] are the default
drivers configured at installation time. Do not remove the [SYSTEM] drivers.

Click

beside the driver you want to remove, then confirm your choice.

Figure 4-8 Removing an Uploaded JDBC Driver
5.

Click Save to save your changes.
If the JDBC driver you remove is one that updated a default driver, the default driver will reappear as
an installed driver the next time you use the New Data Source wizard.

TIBCO Software Inc.

Chapter 4 Data Sources

4.4

JNDI Data Sources
The JNDI data source accesses a database connection previously defined in the application server and published
as a resource or service through JNDI (Java Naming and Directory Interface). Instead of specifying a driver and
database as you do with JDBC data sources, you need to specify only the JNDI service name in your
application server.
Application servers use JDBC connections themselves to expose a database through JNDI. You must
specify the JNDI service name of a JDBC connection. Your application server must also have the
appropriate JDBC drivers and be configured to use them.
Ensure the database user in your JNDI definition has the privileges to run SELECT queries on the tables
used in your reports. In some cases, additional permissions may be required to execute stored
procedures, depending on your configuration and needs. For more information, see A.10.3, “Database
Permissions,” on page 166.

For information about setting up a JNDI connection in your application server, see the following sections:
•
•
•

A.10.7, “JNDI Services on Apache Tomcat,” on page 169
A.10.8, “JNDI Services on JBoss,” on page 170
A.10.9, “JNDI Services on WebLogic,” on page 170

To create a JNDI data source:
1. Log on as an administrator.
2.

Click View > Repository, expand the folder tree, and right-click a folder to select Add Resource > Data
Source from the context menu. If you installed the sample data, the suggested folder is Data Sources. The
New Data Source page appears.

In the Type field, select JNDI Data Source. The information on the page changes to reflect what's needed
to define a JNDI data source.

Fill in the service name. This is the name the application server exposes through JNDI.
You have the option to use attributes in the service name. See 4.1, “Attributes in Data Source
Definitions,” on page 48.

TIBCO Software Inc.

JasperReports Server Community Project Administrator Guide

Figure 4-9 JNDI Data Source Page

4.5

Click Test Connection to validate the data source. If the validation fails, ensure that the values you
entered are correct, that the database is exposed through JNDI, and that the database is running. Also see
the troubleshooting section A.10.7, “JNDI Services on Apache Tomcat,” on page 169.

7.
8.

When the test is successful, click Save. The Save dialog appears.
Enter a name for the data source and an optional description. The Resource ID is generated from the name
you enter. If you haven't already specified a location, expand the folder tree and select the location for your
data source.

Click Save in the dialog. The data source appears in the repository.

AWS Data Sources
Amazon Web Services (AWS) provide computation and data storage on demand in the cloud. We partner with
Amazon to deliver business intelligence solutions based on AWS.
JasperReports Server supports two of the AWS database services as data sources for reporting:
•
•

Amazon Relational Database Service (RDS)
Amazon Redshift data warehouse

JasperReports Server can access either of these services when you define a data source with the correct
configuration information and credentials. The AWS data source wizard uses the AWS credentials you provide
to discover RDS and Redshift data sources. Then it uses those credentials to properly configure security groups
to maintain the connection between JasperReports Server and the AWS data source, even when the IP address
changes. You can access AWS data sources from both stand-alone server instances that you maintain on your

TIBCO Software Inc.

Chapter 4 Data Sources

own computers and virtual server instances that you run on Amazon's Elastic Compute Cloud (EC2). For more
information, see https://www.jaspersoft.com/cloud.

4.5.1

Creating an AWS Data Source
To create an AWS Data Source:
1. Log into JasperReports Server as an administrator.
2.

In the Type field, select AWS Data Source. The information on the page changes to reflect what's needed
to define an AWS data source.

Figure 4-10 Selecting AWS Credentials
4.

Under AWS Settings, specify your Amazon credentials in one of the following ways:
• If your JasperReports Server is running in Amazon's EC2 service, and it has the proper instance role
assigned, the server will detect this and automatically use your EC2 credentials. Using the EC2
instance credentials requires that the role was properly set up and assigned when the instance was
created. If you're using the EC2 service, we strongly recommend that you use the EC2 credentials.
• If your JasperReports Server is not running on Amazon's EC2, enter the AWS credentials associated
with the RDS or Redshift service. If you don't have AWS keys, click Generate credentials, then look
for them on the Outputs tab for your Stack on the Amazon console:

TIBCO Software Inc.

JasperReports Server Community Project Administrator Guide

Figure 4-11 AWS Access and Secret Keys
5.

Under Select an AWS Data Source, specify the connection details of the AWS data source that you want to
connect to:
a.

Select your AWS Region from the drop-down list.

Click the Find My AWS Data Sources button.
The AWS data source queries your environment and displays your available data sources, as shown in
the figure below.

Select your data source.

Enter your user name, password, and database name.
The AWS data source queries your environment and adds the appropriate driver and URL.

Figure 4-12 Select an AWS Data Source Section

TIBCO Software Inc.

Chapter 4 Data Sources

4.5.2

When you've entered all the information, click Test Connection.
If your connection is successful, a message appears to the right of the button. Sometimes the process takes a
few minutes. In that case you'll see an alert. Try the test again after one or two minutes. The test performs
the following actions:
• Validates the user name and password.
• Creates a database security group.
• Adds the IP address of your JasperReports Server instance to the security group to authorize ingress to
the data service (RDS or Redshift).
If you want to control details of the security group name or specify the IP address manually because you
have a complex VPC Topology, see 8.5, “Configuring Cloud Services,” on page 135. You can also
change the default JDBC driver through the configuration.

7.
8.

Click Save. The Save dialog appears.
Enter a name for the data source and a optional description. The Resource ID is generated from the name
you enter. If you haven't already specified a location, expand the folder tree and select the location for your
data source.

Click Save in the dialog. The data source appears in the repository.

Filtering the Regions For AWS Data Source
JasperReports Server automatically displays the regions associated with your AWS credentials when creating an
AWS data source. You can remove regions from the AWS Region drop-down list by editing the .../WEBINF/applicationContext.xml file.
For a list of the supported regions, see the AWS documentation:
https://docs.aws.amazon.com/general/latest/gr/rande.html
To filter AWS regions for your data source:
1. Open the .../WEB-INF/applicationContext.xml file for editing.
2.

Locate the element .

Add the AWS regions you want to remove from the drop-down list within the element. For example:

us-gov-west-1.amazonaws.com
us-gov-east-1.amazonaws.com

4.6

Save the file.

Restart JasperReports Server.

Azure SQL Data Sources
Microsoft Azure provides data storage in the cloud as a service. Microsoft offers different types of storage
options for Azure users, but only the Azure SQL Server database service is currently supported. JasperReports
Server uses the Microsoft SQL Server JDBC driver (tibcosoftware.jdbc.sqlserver.SQLServerDriver), a
management certificate, and your credentials to create a secure connection between JasperReports Server and the
Azure SQL data source.

TIBCO Software Inc.

JasperReports Server Community Project Administrator Guide

4.6.1

Uploading an Azure Certificate File to the Repository
Before you can create an Azure SQL data source, you will need a management certificate to authenticate
JasperReports Server with Azure. The management certificate must be a x.509 certificate and can be either selfsigned or signed by a trusted certificate authority. The certificate can use a public or private key. You will need
to upload the management certificate (.cer) file to the Azure Management Portal and the key exchange (.pfx)
file, which contains the server certificate and the key, to JasperReports Server. You can also store a server
certificate (.cer) file in the repository.
To upload a certificate file to the repository:
1. Log into JasperReports Server as an administrator.

4.6.2

2.
3.

Click View > Repository and expand the folder tree.
Browse to the folder where you want to save the certificate.

Right-click the folder and select Add Resource > File > Azure Certificate from the context menu.

5.
6.

Click Choose File to locate and upload the certificate key exchange (.pfx) or server certificate (.cer) file.
Enter a name and resource ID for the file.

Click Submit to save the file to the repository.

Creating an Azure SQL Server Data Source
The data source wizard uses the Azure credentials that you provide to discover your Azure SQL Server
databases. It then uses those credentials to properly configure access rules to maintain the connection between
JasperReports Server and the data source. For information on configuring access rules for Azure, see
“Configuring Cloud Services” on page 135.
To create an Azure SQL data source:
1. Log into JasperReports Server as an administrator.
2.

In the Type field, select Azure SQL Data Source. The information on the page changes to reflect what's
needed to define an Azure SQL data source.

Figure 4-13 Entering Azure User Information

TIBCO Software Inc.

Chapter 4 Data Sources

Under Azure Settings, enter your Azure subscription ID, user certificate (.pfx) file, and user certificate
password. Click Browse to select the certificate file from your repository. See “Uploading an Azure
Certificate File to the Repository” on page 60 for instructions on uploading the certificate file.

Under Select an Azure Database, specify the connection details of the Azure database that you want to
connect to:
a.

Click the Find My Azure Databases button.
JasperReports Server queries Azure and displays your available SQL Server databases.

Select your database.

Enter your server name, database name, user name, and database name.
The Azure data source queries your environment and adds the appropriate URL.

If you have Microsoft's JDBC driver for SQL Server installed on your JasperReports Server instance,
you can choose to use it instead of the existing JDBC driver by checking Use Microsoft Driver.

Figure 4-14 Selecting an Azure SQL Data Source
6.

When you've entered all the information, click Test Connection.
If your connection is successful, a message appears to the right of the button. Sometimes the process takes a
few minutes. In that case you'll see an alert. Try the test again after one or two minutes. The test performs
the following actions:
• Validates the user name and password.
• Creates firewall access rules to authorize ingress to the data service.
• Adds the IP address of your JasperReports Server instance to the access rule.
If you want to control details of the access rule name or specify the IP address manually, see “Configuring
Cloud Services” on page 135.

7.
8.

Click Save. The Save dialog appears.
Enter a name for the data source and an optional description. The Resource ID is generated from the name
you enter. If you haven't already specified a location, expand the folder tree and select the location for your
data source.

TIBCO Software Inc.

JasperReports Server Community Project Administrator Guide

4.7

Click Save in the dialog. The data source appears in the repository.

Cassandra Data Sources
The Apache Cassandra database provides scalability and high availability for certain applications of big data.
JasperReports Server includes two JDBC drivers for the Cassandra database. We recommend using the JDBC
driver for new Casandra data sources and the native driver for existing Cassandra data sources. See JDBC Data
Sources for information on creating a JDBC data source. For more information about Cassandra, see
http://cassandra.apache.org/.
The native driver for the Cassandra data source has certain limitations on how your data can be structured and
accessed:
•
•
•

The current version of Cassandra does not support NULL values in the data. All required fields must have
non-NULL default values. This also means that input controls cannot be null and must be given a value.
The current version of the driver does not support aggregate functions (sum, min, max).
For query parameters, the current version of the driver supports $X(IN...), but no other $X functions.

The Cassandra data source supports queries in the Cassandra Query Language 3 (CQL3). To improve
performance, design your Cassandra data using the following guidelines:
•
•

Specify the ALLOW FILTERING suffix to speed up queries.
All fields referenced in WHERE clauses of a query should be indexed.

As with all big data stores, Cassandra data sources have the following limitations and usage guidelines within
JasperReports Server:
•
•

4.7.1

Cassandra data sources are not supported for OLAP connections.
You must configure your JVM memory to handle the expected amount of data (see the JasperReports
Server Community Project Installation Guide).

Creating a Cassandra Data Source with the Native Cassandra Driver
1.

Log on as an administrator.

In the Type field, select Cassandra Data Source. The information on the page changes to reflect what's
needed to define a Cassandra data source.
You have the option to use attributes in the values of data source parameters. See 4.1, “Attributes in Data
Source Definitions,” on page 48.

TIBCO Software Inc.

Chapter 4 Data Sources

Figure 4-15 Cassandra Data Source Page
4.

Fill in the required fields, along with any optional information you choose.
Use port 9042 with the Cassandra data source. Cassandra's default port of 9160 is for the Thrift client that is
commonly used with Cassandra. To use the Cassandra Query Language (CQL) with our Cassandra data
source, you may need to configure your Cassandra instance as follows:
start_native_transport: true
native_transport_port: 9042

4.7.2

If you have configured your Cassandra source to be password protected, specify a valid username and
password. Due to compatibility issues, Cassandra authentication is supported only when you use Cassandra
1.12.18 and above.

Click Test Connection to check the values you entered. Make sure that the port is set to 9042, because
the connection test will also work with the wrong port (9160).

7.
8.

When done, click Save. The Save dialog appears.
Enter a name for the data source and an optional description. The Resource ID is generated from the name
you enter. If you haven't already specified a location, expand the folder tree and select the location for your
data source.

Click Save in the dialog. The data source appears in the repository.

Increasing File Descriptor Limits for Cassandra
Many users have reported errors when viewing multiple reports from a Cassandra data source. Cassandra
generally needs more than the default limit of open file descriptors (1024).
To increase the number of file descriptors, administrators need to change the security limits on the Cassandra
nodes and on the operating systems running JasperReports Server.

TIBCO Software Inc.

JasperReports Server Community Project Administrator Guide

To test this configuration, you can increase the limits for the current session with the following Linux
commands:
sudo ulimit -Hn 32768

or
sudo ulimit -Sn 32768

The effects of the commands above will be reset when the computer restarts. To make the changes permanent,
edit the file /etc/security/limits.conf to add the following settings:
* soft nofile 32768
* hard nofile 32768
root soft nofile 32768
root hard nofile 32768
* soft memlock unlimited
* hard memlock unlimited
root soft memlock unlimited
root hard memlock unlimited
* soft unlimited
* hard unlimited
root soft unlimited
root hard unlimited

4.8

MongoDB Data Sources
MongoDB is a big data architecture based on the NoSQL model that is neither relational nor SQL-based. We
provide connectors that allow reports to use a MongoDB data source or a MongoDB JDBC data source.
JasperReports Server also supports Kerberos, SSL, and x509 authentication for MongoDB data sources.
As with all big data stores, MongoDB data sources have the following limitations and usage guidelines within
JasperReports Server:
•
•

4.8.1

MongoDB data sources are not supported for OLAP connections
You must configure your JVM memory to handle the expected amount of data (see the JasperReports
Server Community Project Installation Guide).

Creating a MongoDB Data Source with the Native MongoDB Driver
To create a MongoDB data source with the native driver:
Follow these steps to create a MongoDB data source with the native MongoDB driver.
1.

Log on as an administrator.

Click View > Repository, expand the folder tree, and right-click a folder to select Add Resource > Data
Source from the context menu. If you have installed the sample data, the suggested folder is Data Sources.
The New Data Source page appears.

In the Type field, select MongoDB Data Source. The information on the page changes to reflect what's
needed to define a MongoDB data source.
You have the option to use attributes in the values of data source parameters. See 4.1, “Attributes in Data
Source Definitions,” on page 48.

TIBCO Software Inc.

Chapter 4 Data Sources

Figure 4-16 MongoDB Data Source Page
4.

Fill in the required fields, along with any optional information.
The MongoDB URI has the form: mongodb://:27017/
To enable SSL include the argument ssl=true in the URI. For example:
mongodb://:27017/?ssl=true

To enable x509 authentication for the data source include it as well in the URI. For example:
mongodb://:27017/?ssl=true&authMechanism=MONGODB-X509

To enable Kerberos authentication for the data source include the data source and Kerberos user name in
the URI. For example:
mongodb://:27017/?authMechanism=GSSAPI
Before you can enable x509 authentication you need to set up the Java Secure Socket Extension (JSSE)
in your application server. Before you can enable Kerberos authentication you need to perform the steps
in 4.8.3, “Using Kerberos Authentication with MongoDB Data Sources,” on page 68.

Click Test Connection to validate the data source.

6.
7.

Click Save in the dialog. The data source appears in the repository.

4.8.1.1 The Jaspersoft MongoDB Query Language
MongoDB is designed to be accessed through API calls in an application or a command shell. As a
consequence, it does not have a defined query language. In order to write queries for MongoDB data sources,
we have developed a query language based on the JSON-like objects upon which MongoDB operates. JSON is

TIBCO Software Inc.

JasperReports Server Community Project Administrator Guide

the JavaScript Object Notation, a textual representation of data structures that is both human- and machinereadable.
The Jaspersoft MongoDB Query Language is a declarative language for specifying what data to retrieve from
MongoDB. The connector converts this query into the appropriate API calls and uses the MongoDB Java
connector to query the MongoDB instance. The following examples give an overview of the Jaspersoft
MongoDB Query Language, with the equivalent SQL terms in parentheses:
•

Retrieve all documents (rows) in the given collection (table):
{ 'collectionName' : 'accounts' }

•

From all documents in the given collection, select the named fields (columns) and sort the results:
{
'collectionName' : 'accounts',
'findFields' : {'name':1,'phone_office':1,'billing_address_city':1,
'billing_address_street':1,'billing_address_country':1},
'sort' : {'billing_address_country':-1,'billing_address_city':1}
}

•

Retrieve only the documents (rows) in the given collection (table) that match the query (where clause). In
this case, the date is greater-than-or-equal to the input parameter, and the name matches a string (starts with
N):
{
'collectionName' : 'accounts',
'findQuery' : {
'status_date' : { '$gte' : $P{StartDate} },
'name' : { '$regex' : '^N', '$options' : '' }
}
}

The Jaspersoft MongoDB Query Language also supports advanced features of MongoDB such as map-reduce
functions and aggregation that are beyond the scope of this document. For more information, see the language
reference on the Community website.

4.8.2

Creating a MongoDB JDBC Data Source
If you want to use your MongoDB data source with an SQL query, create a MongoDB JDBC data source. The
MongoDB JDBC driver can create a default normalized schema for your data or, if you prefer, you can load a
schema from the repository or your server file system.
To create a MongoDB JDBC data source:
1. Log on as an administrator.
2.

In the Type field, select MongoDB JDBC Data Source. The information on the page changes to reflect
what's needed to define a MongoDB JDBC data source.
You have the option to use attributes in the values of data source parameters. See 4.1, “Attributes in Data
Source Definitions,” on page 48.

TIBCO Software Inc.

Chapter 4 Data Sources

Figure 4-17 MongoDB JDBC Data Source Page
4.

Fill in the required fields, along with any optional information.

Specify your Connection Options. For example, if you're using MongoDB 3.0 and you want to enable SSL,
enter:
EncryptionMethod=SSL;ValidateServerCertificate=false

To enable both SSL encryption and self-signed CA, enter the TrustStore and KeyStore paths and the
KeyStore password. For example:
EncryptionMethod=SSL;TrustStore=;KeyStore=;KeyStorePassword=;

The Auto Generate Schema Definition check box is checked by default. With this option selected, When
you first connect to a MongoDB server, the driver automatically creates a normalized schema of the data
and generates a SchemaDefinition for housing and sharing the normalized schema.
6.

To specify a schema you've created, uncheck this box and:

TIBCO Software Inc.

JasperReports Server Community Project Administrator Guide

Use the File Source drop down to select your schema file location: Repository or Server File System.
To create a schema using the schema tool, see “Creating a Schema with the Schema Tool” on
page 69

If your file is in the repository, click the Browse button and locate it in the repository. If your file is in
your server file system, enter the path in the Server File Location text box. To upload a schema to the
repository, see “Uploading a Schema to the Repository” on page 69

Click Test Connection to validate the data source.

8.
9.

10. Click Save in the dialog. The data source appears in the repository.

4.8.3

Using Kerberos Authentication with MongoDB Data Sources
The native MongoDB driver can connect to MongoDB Enterprise using Kerberos Authentication. Kerberos is a
network authentication protocol that allows clients and servers on a non-secure network to use "tickets" to
identify themselves.
To use Kerberos authentication, you need to set up the following:
1. Install the Kerberos client tools on the JasperReports Server host. The client tools are included in the
JDK/JRE for Windows. Client tools packages are available for Linux and OS X. You will be prompted to
enter information on your Kerberos system during the installation.
2.

Download the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy files from Oracle
and install them on the JasperReports Server. The files are available for download at the Oracle Java SE
Downloads page.

Set these Java system properties for JasperReports Server:

java.security.krb5.realm=
java.security.krb5.kdc=
javax.security.auth.useSubjectCredsOnly=false
java.security.auth.login.config=/jaas.conf

Edit the jaas.conf file to add the following:

com.sun.security.jgss.krb5.initiate {
com.sun.security.auth.module.Krb5LoginModule
required
useTicketCache=true
doNotPrompt=true;
};

Run the kinit mongodb/[mongo-db-hostname]@ command on the JasperReports
Server host to create or renew a ticket for the Kerberos user. This is the account you will enter as the user
name for the data source.

TIBCO Software Inc.

Chapter 4 Data Sources

4.8.4

Creating a Schema with the Schema Tool
To create a schema with the schema tool:
1. Go to /buildomatic/tools and double click the schematool.jar file.
2.

Follow the instructions in the schema tool documentation found here:
https://documentation.progress.com/output/DataDirect/jdbcmongohelp/index.html#page/mongohelp/startingthe-schema-tool.html

4.8.5

Uploading a Schema to the Repository
To upload a schema to the repository:
1. Click View > Repository and expand the folder tree.

4.9

Right-click a folder and select Add Resource > File > MongoDB JDBC Schema from the context menu.

Use the Upload File From Your Local Computer page to locate and upload your schema file.

File Data Sources
File-based data sources read a text file in JSON, XML, or XMLA format and allow you to query its contents as
a relational table. A text file in JSON format may be stored in the server's repository, in the server's file system,
while a text file stored in JSON, XML, or XMLA format can be accessed from a URL. This means you can
create a data source based on data retrieved from websites and even REST APIs.
Domains support file-based data sources, such as text files in JSON and XML format as well as Excel files.
These file-based data sources support features domain-related features like returning JDBC metadata, creating
derived tables, supporting calculated fields, domain pre-filtering, joining other data sources in a virtual data
source, and full support in the Domain Designer.
Older file-based data sources, which presented domain data in a single flat table and lack the features of the
newer data sources, appear in the Type drop-down menu with (Before 6.4) next to their names.
By default file data sources do not appear in the New Data Source dialog and must be enabled first.
The following file-based data sources are available:
•
•
•
•
•
•
•

Remote XML data source (Simple single-table support and full domain support)
JSON data source (Simple single-table support and full domain support)
JSON Series data source (Simple single-table support)
JSONQL (JSON Query Language) data source (Simple single-table support and full domain support)
Text (CSV) data source (Full domain support)
XMLA Query data source (Simple single-table support)
XLS and XLSX data sources (Full domain support)

Note that if there are two versions of a file-based data source type in the .../WEB-INF/applicationContextremote-services.xml file, the version with full domain support has a 2 at the end of its name.
To enable file data sources in the UI:
1. Open the file .../WEB-INF/applicationContext-remote-services.xml for editing.
2.

Locate the element .

Comment out the file data sources you want to display.

TIBCO Software Inc.

JasperReports Server Community Project Administrator Guide

Save the file and restart JasperReports Server.

In the following example, the JSON and XML data sources with simple domain and full domain support are
commented out so they appear in the Type drop-down menu:

Edit the file .../WEB-INF/web.xml to make the following changes.
a.

Locate the ClusterFilter given in comments and uncomment it as follows:

ClusterFilter
com.jaspersoft.jasperserver.war.TolerantSessionFilter

132

TIBCO Software Inc.

Chapter 8 System Configuration

Locate the corresponding mapping for the ClusterFilter and uncomment that, too. You must also
uncomment the element below it as follows:

ClusterFilter
/*

Add the following property to your JVM environment:
-Dorg.apache.catalina.session.StandardSession.ACTIVITY_CHECK=true

8.4

Restart your Apache Tomcat application server.

Enabling Data Snapshots
The data snapshot feature stores report data in the server, which can change in the user experience significantly:
•

•

Without data snapshots – Whenever users run a report, the server queries the data source and displays the
latest data. When the same report is run over and over, the data source is often returning the same data
every time. This is the default behavior.
With data snapshots – The first time a report runs, it queries the data source and stores a copy of the data
with the report in the repository. Users who view the report later see the data from the saved snapshot, not
from querying the data source. Reports accessed through web service APIs are also based on the saved
snapshot. For large reports or frequently viewed reports, the persisted snapshot provides a significant
performance gain and reduces load on your data sources. Every user who has access to the report will see
the data from the same snapshot. For users who require it, the report viewer provides a button to manually
refresh the data snapshot anytime. In addition, when the scheduler runs a job on a report it always updates
the snapshot. Enable data snapshots if you'd like to use them.

We encourage enabling data snapshots with the following recommendations:
•
•

•

8.4.1

If you have a new installation of JasperReports Server, enable snapshots to get the full server functionality.
In the future, persistent data snapshots may be enabled by default.
If you're upgrading from an early release that predates data snapshots, first follow the upgrade procedure and
verify the outcome, as instructed in the JasperReports Server Community Project Installation Guide. Then,
before enabling data snapshots, notify your users about this new functionality.
Data snapshots are stored in the server's repository, which must be sized accordingly. If you have a large
number of reports, or very large reports, consider the performance of your repository database before
enabling snapshots. If your users rely on data that changes frequently or if they expect to see real-time data
when opening a report, do not enable snapshots. Alternatively, you can enable snapshots selectively as
described below.

Global Data Snapshot Configuration
The server-level settings determine whether the snapshot feature is available on the server.

TIBCO Software Inc.

133

JasperReports Server Community Project Administrator Guide

Data Snapshots Server-Level Configuration
Configuration File
.../WEB-INF/applicationContext-data-snapshots.xml
Property

Bean

Description

snapshot
Persistence
Enabled

dataSnapshot
Service

When set to true, it allows the JasperReports Server report
viewer to save data snapshots in the repository and open
them the next time the report is run. By default, this is set to
false.

There is also a property named snapshotRecordingEnabled that caches a snapshot in the report
viewer memory when sorting and filtering columns interactively. This allows the report viewer to
refresh the display without querying the database every time. Regardless of persistence,
snapshotRecordingEnabled improves report viewing performance and decreases database load,
so it should remain set to true.

8.4.2

Report-level Data Snapshot Configuration
You can disable snapshots on a specific report by setting the following property in the report's JRXML:
net.sf.jasperreports.data.cache.persistable=false
This report-level property depends on the snapshot mechanism in JasperReports Server. This
property has no effect in other report viewers without such a mechanism, like the viewer integrated in
Jaspersoft Studio.

There are two ways to control snapshots at the report level. In the case above:
•
•

Data snapshots are enabled on the server, so most reports use them.
Reports that don't benefit from data snapshots can explicitly disable snapshots in their own JRXML.

As with all report-level properties, you can set server-wide default values, as described in 8.6, “Configuring
JasperReports Library,” on page 138:
Data Snapshots Default Report-Level Configuration
Configuration File
.../WEB-INF/classes/jasperreports.properties

134

Property

Description

net.sf.jasperreports.data.cache.
persistable=false

When set to false, the server-wide default for reports is to
not use data snapshots, however, they are still available if
a report overrides this value to true in its own JRXML.

TIBCO Software Inc.

Chapter 8 System Configuration

Because the report-level property takes precedence over the server-level property, this enables a second way to
control snapshots:
•
•
•

Data snapshots are enabled on the server.
But the server-wide default is set to false, so most reports don't use them.
Reports that benefit from data snapshots can explicitly enable snapshots in their own JRXML with:
net.sf.jasperreports.data.cache.persistable=true

8.4.3

Data Snapshots in the Scheduler
Scheduled jobs always run the report by accessing the data source, so the output has up-to-the-minute data.
When data snapshots are enabled on reports, the job always updates the data snapshot with this new data after it
runs. This way, when you schedule a report, it also refreshes the data snapshot periodically: hourly, daily,
weekly, or whatever suits your data requirements.
When data snapshots are enabled on the server, the scheduler interface has an extra option to output the data
snapshot. This option, as shown in the following figure, generates a copy of the report with the new data
snapshot. This copy is stored in the repository as a JasperReport, identical to the report being run. Over time,
this will create an archive of your report data.
If you clear the Data Snapshot Output Format option, no copy of the report is saved with the new data snapshot,
but the data snapshot on the original report is still updated when the job runs. Also, you must select at least one
other output format to schedule the report.

Figure 8-3 The Data Snapshot Output Option in the Scheduler
Finally, when data snapshots are enabled, you can also update them through REST web services calls. When
specifying the report to run with the rest_v2/reportExecutions service, you can add arguments to explicitly
update or not update the associated data snapshot. For more information, see the JasperReports Server REST API
Reference.

8.5

Configuring Cloud Services
The following settings control how JasperReports Server interacts with a cloud service provider, such as AWS
and Microsoft Azure:
•

•
•

The Cloud Settings page enables you to create and change firewall rules without restarting the server. For
the Microsoft Azure service, these rules are called "access rules." For AWS, they are called "security
groups."
The AWS configuration file allows you to change the JDBC driver used for AWS data sources.
The Azure configuration file allows you to change the JDBC driver and URL template used for Azure data
sources.

TIBCO Software Inc.

135

JasperReports Server Community Project Administrator Guide

For more information about AWS and Azure data sources, see 4.5, “AWS Data Sources,” on page 56 and
“Azure SQL Data Sources” on page 59.

8.5.1

Changing Cloud Services Settings
To change cloud services settings:
1. Log in as administrator (jasperadmin by default).
2.

Click Manage > Server Settings. The Log Settings page appears.

Click Cloud Settings in the left-menu.
The Cloud Settings panel appears.

Figure 8-4 Cloud Settings Page
We set up one AWS DB Security Group (using IP address) in each RDS region, per JasperReports
Server instance. The security group allows connections from the specific JasperReports Server
instance to the specified AWS database instance.

136

Modify the following settings and click Change after each modification. Changes are effective
immediately on the server:
• Automatically Set Up an Access Rule for JasperReports Server: This check box is generally left
checked. When checked the JasperReports Server will automatically create and update an access rule
that allows connections from JasperReports Server to the database hosted by the cloud service provider.
If you want to manage access rules manually, uncheck this box.

TIBCO Software Inc.

Chapter 8 System Configuration

•

•
•

•

8.5.2

Access Rule Name: When JasperReports Server creates access rules to support cloud-based data
sources on this instance, it will use this name as the basis of the access rule name. When the
JasperReports Server instance is running on AWS EC2, the EC2 instance ID will be appended. When
running outside of AWS EC2, you must make sure that name is unique among JasperReports Server
instances (i.e., each instance should have its own name), so the IP addresses are properly granted access
to the appropriate database instances.
Access Rule Description: This text will be used as the description for the access rule.
JasperReports Server Public IP: Enter the public IP address for JasperReports Server. Most users on
AWS EC2 should leave the this field empty and let JasperReports Server determine the IP address
automatically. It is possible with complex EC2 topology involving Virtual Private Clouds (VPCs) that
you need to provide your IP address manually.
Suppress EC2 Credentials Warning: If your JasperReports Server instance was created with no
IAM role, when you go to the data source wizard to add an AWS data source with EC2 credentials
there will be a warning message saying there is no proper role set. Checking this box suppresses the
warning and disables the option.

Changing the Default JDBC Driver for AWS Data Sources
When adding an AWS data source, JasperReports Server uses the JDBC driver specified in the .../WEBINF/applicationContext-webapp.xml file. You can configure JasperReports Server to use a different JDBC driver.
To change the JDBC driver used with AWS data sources:
1. Open the file .../WEB-INF/applicationContext-webapp.xml for editing.
2.

Locate the jdbcConnectionMap bean and the key of your AWS database type within it. Modify this key to
specify a different JDBC driver. For example, the default driver for MySQL databases is set to the MariaDB
driver:

...

8.5.3

Save the file and restart JasperReports Server.

Changing Azure SQL Data Source Defaults
When creating an Azure SQL data source, JasperReports Server uses the JDBC driver and JDBC connector URL
template specified in the .../WEB-INF/applicationContext-azure-sql-datasource.xml configuration file. You have
the choice of changing the URL string and using the Microsoft JDBC driver for SQL Server when creating the
data source or you can change the default driver and URL string in the configuration file.

TIBCO Software Inc.

137

JasperReports Server Community Project Administrator Guide

Azure Data Source Defaults
Configuration File
.../WEB-INF/applicationContext-azure-sql-datasource.xml
Bean

Description

defaultAzureJdbcDriverClassName

The JDBC driver used for Azure SQL Server data sources. The
default is the native JDBC driver for SQL Server
(tibcosoftware.jdbc.sqlserver.SQLServerDriver).

defaultAzureJdbcUrlSyntax

The template for the JDBC connector URL for Azure SQL Server
data sources. The connector string contains properties required for
the JDBC driver to access the Azure data source. The default string
specifies the server name, database name, and the use of SSL as
an encryption method.

Configuration File
.../WEB-INF/applicationContext-webapp.xml

8.6

Bean

Description

defaultAzureKeyStoreType

The file format for storing the certificate key exchange files used for
Azure data sources. The default file format is pkcs12.

Configuring JasperReports Library
JasperReports Server's reporting features are built on the JasperReports Library, which is embedded in the server.
Many of the options you can configure to change the server's functionality are actually JasperReports Library
options. The configuration options can control many aspects of the server's behavior, from the way reports are
exported into different file formats, to the default font.
These options can be set at different levels:
•
•
•

Global – Applies to all reports generated by the server. Global JasperReports properties are defined in the
.../WEB-INF/classes/jasperreports.properties file.
Report – Defined in the JRXML of the report and applies to that specific report.
Element – Defined in the JRXML and applies to specific elements of the report.

For more information about JasperReports Library configuration, see
http://jasperreports.sourceforge.net/config.reference.html.
The following sections highlight a few of the available options:
•
•
•
•
•
•

138

Extending JasperReports Library
Changing the Crosstab Limit
Setting a Global Chart Theme
Disabling Interactivity in the Report Viewer
Disabling Chart Types in Dashboards
Changing the Pro Charts Rendering Engine

TIBCO Software Inc.

Chapter 8 System Configuration

•
•
•

8.6.1

Configuring a JavaScript Engine for Graphical Report Rendering
Static Export Properties for High Charts
Enabling PDF Accessibility Features in Tables

Extending JasperReports Library
You can extend JasperReports Library by implementing the public interfaces it exposes.
Such an implementation is usually stored in a JAR (Java Archive) that contains a file called jasperreports_
extension.properties, and specifies a factory class used to instantiate an extension registry. The extension registry
specifies one or more extension objects, each of which corresponds to a JasperReports Library extension point
represented by a Java interface.
Place this JAR on the JasperReports Library classpath, and your extension is automatically available.
For more information, refer to JasperReports Library Ultimate Guide.

8.6.2

Changing the Crosstab Limit
If you use crosstab reports, you may experience Out of Memory errors if the reports are very large or complex.
You can configure JasperReports Server to return a message instead of memory errors when users run such
crosstabs. To do so, enable the net.sf.jasperreports.crosstab.bucket.measure.limit property and set
its maximum value in the following configuration file:
Crosstab Report Configuration Option
Configuration File
.../WEB-INF/classes/jasperreports.properties
Property

Description

net.sf.jasperreports.
crosstab.bucket.
measure.limit

This value effectively limits the number of cells in a crosstab,
which can be computed as follows:
(number of crosstab rows) x (number of crosstab columns) x
(number of user-defined measures + 1)
The default value is 100000.
Enter large values to allow your users to create larger, more
complicated crosstabs; enter small values to restrict them. If you
experience OutOfMemoryExceptions after changing this
value, try setting it to a smaller number, or configure your JVM to
allow more memory to be used.

8.6.3

Setting a Global Chart Theme
Chart themes control the look and feel of the charts generated by JasperReports Server. Chart themes can be
applied at the level of either the server or the individual report:

TIBCO Software Inc.

139

JasperReports Server Community Project Administrator Guide

•

To apply a theme at the report level, select it when designing the report in Jaspersoft Studio. Note that you
can also apply a theme to individual chart elements. Note that a chart theme can be included in a report
unit as a resource. In this case the theme is available only to charts in that report unit.
To apply a theme at the server level, copy the chart theme JAR to the correct location and edit its
configuration file.

A chart theme is a JAR file that defines the look and feel of a chart. Once you have created the chart theme JAR
file, copy it to the .../WEB-INF/lib directory. Chart themes in this location are available to any chart in the
instance of the server. They can also be set as the global chart theme.
To set a theme as the default chart theme, edit the following configuration file:
Global Report Theme
Configuration File
.../WEB-INF/classes/jasperreports.properties
Property

Description

net.sf.jasperreports.
chart.ChartTheme

The name of a chart theme that is in the .../WEB-INF/lib
directory.

We recommend that you create your chart themes in Jaspersoft Studio. Click File > New > Other > Chart
Theme, then use Jaspersoft Studio to archive the new chart theme as a JAR.
Chart themes do not apply to Ad Hoc chart views.

8.6.4

Disabling Interactivity in the Report Viewer
By default, the report viewer's interactivity is enabled, and reports with interactive elements (such as the table
component) are interactive when run in the web server and displayed in the viewer. If you don't want your
reports to be interactive, you can disable interactivity across all reports by editing the following configuration
file.
Interactivity in the Report Viewer
Configuration File
.../WEB-INF/classes/jasperreports.properties
Property

Description

net.sf.jasperreports.
components.table.interactive

By default, this property is set to true; in this case,
interactivity is enabled in the report viewer. Set it to false
to disable interactivity.

Changing this setting in this configuration file changes the behavior for the entire server. To configure this
behavior at the report, table, or column level, edit the report's JRXML properties in Jaspersoft Studio.

140

TIBCO Software Inc.

Chapter 8 System Configuration

8.6.5

Disabling Chart Types in Dashboards
By default, interactivity is enabled in charts that appear in dashboards, and users can change the chart type by
clicking on the chart type selector (gear icon). If you don't want users to modify the chart types, you can disable
the chart type selector on all dashboard charts by editing the following configuration file.
Chart Type Selector in Dashboards
Configuration File
.../WEB-INF/classes/jasperreports.properties
Property

Description

com.jaspersoft.jasperreports.
highcharts.interactive

By default, this property is set to true; in this case, chart
types can be modified in dashboards. Set it to false to
prevent users from changing dashboard charts.

Changing this setting in this configuration file changes the behavior for the entire server. To configure this
behavior at the report level, edit the report's JRXML properties in Jaspersoft Studio.

8.6.6

Changing the Pro Charts Rendering Engine
By default, JasperReports Server renders Pro Charts (those based on Fusion Charts) using HTML5. If your
browser doesn't support HTML5, the chart isn't be rendered unless you change the configuration. Though we
don't recommend it, you can instead have these elements rendered by Adobe Flash; in some circumstances,
Fusion's Flash solution may pose a security risk.
Note that Pro Charts are available only in the JasperReports Server Professional edition.
To render Pro Charts using HTML5, edit the following configuration file:
Pro Charts Renderer
Configuration File
.../WEB-INF/classes/jasperreports.properties
Property

Description

com.jaspersoft.jasperreports.
fusion.charts.render.type

Determines which of the following renderers is
used:
•
•

html5 is the default renderer for Pro Charts.
It is our preferred renderer.
flash is a deprecated renderer for Pro
Charts.

Note that this property applies only to reports that rely on Pro Charts and affects only the HTML preview and
export.

TIBCO Software Inc.

141

JasperReports Server Community Project Administrator Guide

Typically, this property is set at the server level; to override the server-level setting for a specific Pro Chart
report, set this property at the report level, and also specify a second property as shown:
net.sf.jasperreports.print.transfer.fusion=com.jaspersoft.jasperreports.fusion

This allows the reporting engine, JasperReports Library, to recognize the Fusion settings. If this property isn't
set, the com.jaspersoft.jasperreports.fusion.charts.render.type property is ignored at the report
level.

8.6.7

Configuring a JavaScript Engine for Graphical Report Rendering
Depending on the circumstances, a given graphical element (such as a chart, a map, or a widget) in a report can
be rendered in two ways:
•
•

When run directly in the web UI, the browser itself renders the chart.
When scheduled to run later or run in the background, an internal engine renders the chart.

By default, JasperReports Server's internal JavaScript engine is Rhino, which is an excellent solution for most
cases; most JasperReports Server users can accept this default. However, you may want to investigate other
engines if you encounter any of the following issues when scheduling chart-based reports or running them in
the background:
•
•
•
•

Poor performance when generating complex charts or charts that contain large volumes of data.
Out of memory messages.
Incorrect scaling when certain Pro Chart reports are printed.
Results that don't match those generated when the report is run directly in the web UI. For example, text
elements incorrectly sized or placed.

An alternative engine is provided in our installers; PhantomJS executes JavaScript when generating graphical
reports that are run in the background or scheduled. PhantomJS is a headless WebKit with JavaScript API. To
use PhantomJS when JasperReports Server is installed from the WAR file, download the correct version for your
environment from PhantomJS and install it on the computer hosting JasperReports Server. For installation
instructions, refer to the documentation provided with PhantomJS.
Once PhantomJS is installed, point JasperReports Server to its location. You can configure several processes to
use PhantomJS: HighCharts generation, Pro Charts generation (including Pro Widgets and Pro Maps), and
exporting dashboards.
These are a server-wide settings. In a given server, all charts of the same type (HighCharts or Fusion
(Charts Pro, Maps Pro, or Widgets Pro) use the same JavaScript engine.
You can't use PhantomJS to render JFreeCharts. Such reports are always generated by Rhino when run
in the background or scheduled.

To configure JasperReports Server to use PhantomJS for HighCharts and Pro Charts, including Pro Widgets and
Pro Maps, edit the following properties:
JavaScript Engine Configuration for HighCharts and Pro Charts
Configuration File
.../WEB-INF/classes/jasperreports.properties

142

TIBCO Software Inc.

Chapter 8 System Configuration

JavaScript Engine Configuration for HighCharts and Pro Charts
Property

Description

net.sf.jaspersoft.jasperreports.
phantomjs.executable.path

This property points to the engine the server should use to
generate HighCharts-based and Pro Charts-based charts in
reports run in the background or scheduled.
For example, if you're using Windows and you expanded the
PhantomJS 2.0 ZIP file into the root of your C: drive:
net.sf.jaspersoft.jasperreports.phantomjs.
executable.path=C:\\phantomjs-2.0windows\\phantomjs.exe

com.jaspersoft.jasperreports.
components.customvisualization.
phantomjs.executable.path

This property points to the engine the server should use for
exporting Jaspersoft Studio reports with custom visualization
components. See the Jaspersoft Studio User Guide for more
information.

com.jaspersoft.jasperreports.
phantomjs.tempdir.path

The temporary directory where PhantomJS stores its output. By
default, JasperReports Server expects this output in the
location defined by Java's java.io.tmpdir system property.

com.jaspersoft.jasperreports.
phantomjs.executable.timeout

The maximum number of milliseconds to wait for output from
PhantomJS before the chart times out. The default is 3000.

PhantomJS can also be used to render dashboards when exporting them to a PNG, PDF, ODT, or DOCX file. To
support Japanese and Chinese fonts, as well as certain icons in dashboard output, Jaspersoft recommends using
PhantomJS 2.0 or later.
If you are using JasperReports Server and PhantomJS on a Windows platform, exporting large Fusion
reports may cause issues. In those cases, we recommend editing the properties as follows:
•
•

Change net.sf.jaspersoft.jasperreports.phantomjs.executable.path to
com.jaspersoft.jasperreports.fusion.phantomjs.executable.path.
Set com.jaspersoft.jasperreports.fusion.phantomjs.executable.timeout to 600000 to
increase the timeout period.

To configure JasperReports Server to use PhantomJS for exporting dashboards, edit the following property:
JavaScript Engine Configuration for Dashboards
Configuration File
.../WEB-INF/js.config.properties

TIBCO Software Inc.

143

JasperReports Server Community Project Administrator Guide

JavaScript Engine Configuration for Dashboards
Property

Description

phantomjs.binary

This property points to the engine the server should use to
generate dashboards when exporting.
For example, if you are using Windows and you expanded the
PhantomJS 2.0 ZIP file into the root of your C: drive:
phantomjs.binary=C:\\phantomjs-2.0windows\\phantomjs.exe

After setting this property, restart JasperReports Server to enable it.

8.6.8

Static Export Properties for High Charts
When you create interactive JasperReports that use Highcharts, and those reports are exported to HTML, the

JasperReports Server Community Project Administrator Guide Jasper Reports CP Admin

Navigation menu

Versions of this User Manual:

Views

Navigation