JASPERSERVER

ADMINISTRATOR GUIDE
RELEASE 3.7

http://www.jaspersoft.com
JasperServer Administrator Guide

© 2010 Jaspersoft Corporation. All rights reserved. Printed in the U.S.A. Jaspersoft, the Jaspersoft logo, JasperAnalysis,
JasperServer, JasperETL, JasperReports, JasperStudio, iReport, and Jasper4 products are trademarks and/or registered
trademarks of Jaspersoft Corporation in the United States and in jurisdictions throughout the world. All other company and
product names are or may be trade names or trademarks of their respective owners.
This is version 0110-JSP37-7 of the JasperServer Administrator Guide.

2
 Table of Contents

TABLE OF CONTENTS
1 Introduction to JasperServer Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.1 Overview of Organizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.1.1 Single Default Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.1.2 Multiple Organizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.1.3 Delegated Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.2 Overview of the Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.2.1 Folder Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.2.2 Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.2.3 Sample Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.3 Overview of Users and Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.4 Logging In . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.4.1 Single Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.4.2 Multiple Organizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.4.3 JasperServer Heartbeat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.5 Administrator Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

2 Organization, User, and Role Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

2.1 Scope of Administrative Privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.2 Managing Organizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
2.3 Managing Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.4 Managing Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

3 Repository Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.1 Managing Folders and Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.1.1 Creating a New Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.1.2 Adding Resources to the Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
3.1.3 Renaming a Folder or Resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
3.1.4 Viewing a Report or Dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
3.1.5 Modifying an Ad Hoc Report or Dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
3.1.6 Editing a Resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

3
JasperServer Administrator Guide

3.1.7 Copying Folders or Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

3.1.8 Moving Folders or Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
3.1.9 Deleting Folders or Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
3.2 Access Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
3.2.1 Authentication Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
3.2.2 Authorization Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
3.2.3 Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
3.2.4 Assigning Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
3.2.5 Testing User Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
3.3 Multiple Organizations in the Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
3.3.1 Design Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
3.3.2 Referencing Resources in the Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
3.3.3 Best Practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

4 Import/Export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
4.1 Importing Repository Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
4.2 Exporting Repository Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
4.3 Encrypting the Repository Database Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

5 System Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
5.1 Configuring Password Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
5.1.1 Enabling Password Expiration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
5.1.2 Allowing Users to Change their Passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
5.2 Changing the Login Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
5.3 Ad Hoc Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
5.3.1 Ad Hoc Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
5.3.2 Managing the Ad Hoc Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
5.3.3 Configuring Dataset Expiration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
5.4 Disabling the Domain Validation Check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
5.5 Configuring JasperReports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
5.5.1 Extending JasperReports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
5.5.2 Changing the Crosstab Limit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
5.5.3 Setting a Global Chart Theme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
5.6 Configuring the Heartbeat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
5.7 Removing Report Scheduling Interval Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
5.8 Special Domain Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
5.8.1 Enabling Oracle Synonyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
5.8.2 Enabling CLOB Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
5.8.3 Enabling Proprietary Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
5.9 Custom Data Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
5.9.1 Data Sources in JasperServer and JasperReports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
5.9.2 JasperServer Data Sources and Query Executors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
5.9.3 Overview of the Example Custom Data Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
5.9.4 Prerequisites and Installation of the Example Custom Data Sources . . . . . . . . . . . . . . . . . 57
5.9.5 Creating a Custom Data Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

4
 Table of Contents

5.9.6 Installing a Custom Data Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

5.9.7 Using a Custom Data Source in Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
5.10 Configuring the Online Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
5.11 Configuring Search Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

6 Auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
6.1 Audit Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
6.2 Configuring Auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
6.2.1 Enabling Auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
6.2.2 Archive Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
6.2.3 Events and Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
6.3 Using the Audit Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
6.3.1 Domain Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
6.3.2 Sample Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
6.4 Importing and Exporting Audit Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

7 Integrating JasperServer and Talend Integration Suite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

7.1 Configuring ETL Administrators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
7.2 Testing Integration with TIS EE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

8 Integrating JasperServer and Liferay Portal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

8.1 Changing Liferay’s Port Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
8.2 Configuring JasperServer to Accept Web Services Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
8.3 Configuring Liferay to Access JasperServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
8.4 Testing Liferay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
8.5 Deploying the JasperServer Portlet WAR File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
8.6 Configuring a Default Report to Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
8.7 Testing the JasperServer Portlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
8.8 JasperServer Portlet Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
8.8.1 Portlet Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
8.8.2 Example Server and Browser Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
8.9 Setting up JasperReports Hyperlinks for Use in a Portlet Environment . . . . . . . . . . . . . . . . . . . . . . . . 77

9 Localization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
9.1 UTF-8 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
9.1.1 Tomcat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
9.1.2 JBoss . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
9.1.3 MySQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
9.1.4 Oracle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
9.2 Creating a Locale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
9.2.1 About Properties Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
9.2.2 Creating a Resource Bundle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
9.2.3 Changing Format Masks and Date Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
9.3 Configuring JasperServer to Offer a Locale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
9.3.1 Specifying Additional Locales . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

5
JasperServer Administrator Guide

9.3.2 Specifying Additional Time Zones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

9.3.3 Setting a Default Time Zone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
9.4 Character Encoding and Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
9.4.1 Changing Character Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
9.4.2 Working with Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
9.5 JasperBabylon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

6
 Introduction to JasperServer Administration

1 INTRODUCTION TO JASPERSERVER ADMINISTRATION

JasperServer builds on JasperReports 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 providing shared services, such
as security, a repository, and scheduling. JasperServer exposes comprehensive public interfaces enabling seamless integration
with other applications and the capability to easily add custom functionality.
The heart of the Jaspersoft BI Suite is JasperServer, which provides the ability to:
Š Easily create new reports using an intuitive web-based drag and drop Ad Hoc reporting interface.
Š Efficiently and securely manage many reports.
Š Interact with reports, including entering parameters and drilling on data.
Š Arrange reports and web content to create appealing, data-rich dashboards that quickly convey business trends.
For creating analysis views and OLAP client connections, Jaspersoft offers JasperAnalysis, which runs on JasperServer. This
optional component is described in the separate JasperAnalysis User Guide.
The core of the JasperServer architecture is the repository that stores the reports, dashboards, analysis views, and all the
resources these depend upon. Users have a password protected user account, and once logged in, they run report, dashboards,
and analysis views from the repository. The repository has role-based permissions to control access to resources. When users
create reports and dashboards of their own in the designer tools, they save them in a writable folder of the repository.
This guide covers how to administer the users, roles, resources, and settings in JasperServer to ensure security and
performance. This guide also covers how to manage organizations and perform auditing of JasperServer, a new feature of this
release.
If you want to extend your knowledge of Jaspersoft BI software, our Ultimate Guides document advanced features and
configuration. They also include best practice recommendations and numerous examples. The guides are available as
downloadable PDFs. Community project users can purchase individual guides or bundled documentation packs from the
Jaspersoft online store. Professional and Enterprise customers can download them freely from the support portal.

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

This chapter contains the following sections:

Š Overview of Organizations
Š Overview of the Repository
Š Overview of Users and Roles
Š Logging In
Š Administrator Pages

7
JasperServer Administrator Guide

1.1 Overview of Organizations

The architecture of JasperServer supports organizations, logical entities within JasperServer that have their own users, roles,
and branch of the repository. Organizations may have sub-organizations to mimic any business structure or hierarchy.
The structure of the repository is determined by the organizations in your deployment. In the default installation, there is a
single organization that mimics the simple structure in older versions of JasperServer. If you want to deploy multiple
organizations, there are many design considerations you must be aware of.

1.1.1 Single Default Organization

After a default installation, JasperServer contains a single organization into which you can deploy your reports. For example,
if you install the sample data, you see a single organization that holds all sample resources, users, and roles.
Single organizations are designed to handle most business cases and are straightforward to administer. Even in a single
organization, there is a system admin and an organization admin that share administrative duties. If your business needs call
for more organizations, you will have to manage several levels of administrators and possibly create shared resources in the
repository. The following sections provide use cases and explain the multiple levels of administrators.
Unless otherwise stated, the rest of this guide documents the single organization architecture that is the default installation
with JasperServer.

1.1.2 Multiple Organizations

There are many usage scenarios for organizations within JasperServer:
Š An application provider, such as a software-as-a-service company or a computer department, has a hosted application
being offered to many customers and integrates JasperServer to offer dashboards, reports, and analysis. There are a
number of common reports and data sources that are useful across customers, but there are customer specific reports as
well. Machines and databases are shared by customers, according to the provider’s own architecture, but within the
functionality provided by JasperServer, each customer is a separate organization. Customers can manage their own users
in the hosted application, and JasperServer maps the application’s authentication scheme to the correct organization. The
organization mechanism provides the full power of JasperServer to each of the provider’s customers, while ensuring that
their data and reports are secure.
Š A company has many departments but wants to consolidate the BI environment so that all departments are sharing a
common BI infrastructure. Corporate IT only needs to deploy and maintain a single instance of JasperServer, and each
department is represented by an organization that manages its own users. For security and simplicity, the departments do
not share databases, except in the case of sub-departments, such as Accounts Payable being a sub-department of Finance.
Users access JasperServer directly, logging in with their department name and user name. Within a department,
organization administrators have defined the data sources and Domains specific to the needs of their department’s users.
The design of the organization feature is flexible enough to accommodate any combination of these and many other usage
scenarios. In all cases, administrators can configure secure environments for any number of organizations, and end-users
experience a powerful BI platform that is tailored to their needs.
Each organization or hierarchy of organizations co-exists independently within the same instance of JasperServer.
JasperServer isolates neighboring organizations from each other but allows parent organizations to have full control over their
sub-organizations. Users may only access data and resources within their organization or a sub-organization, and
administrators may define roles and set permissions to further restrict access.

1.1.3 Delegated Administration

Each organization has an administrator who can manage users, roles, and repository permissions within the organization. The
administration of organizations is hierarchical, meaning that the administrator can also manage all users and roles within sub-
organizations of any level.
When there are sub-organizations, the administrator of the parent organization can either manage their users and roles, or
delegate those tasks to an administrator within each sub-organization. The administrator of a sub-organization is limited to
accessing resources and managing users and roles within the sub-organization, thereby maintaining the security of the parent
organization and any of the parent’s other sub-organizations.

8
 Introduction to JasperServer Administration

There are essentially three levels of administration:

Š The system administrator – Also called system admin. The system admin is the superuser login, outside of all
organizations, that manages the JasperServer installation, creates top-level organizations, and manages server-wide
settings. The system admin can create, modify, and delete users, roles, and repository objects of any organization.
Š The administrator of a top-level organization – Also called organization admin. The organization admin manages all
users, roles, and repository objects within an entire organization, including any sub-organizations. The default login name
of the organization admin is jasperadmin.
Š The administrator of a sub-organization – Functionally equivalent to an organization admin, but due to the hierarchy of
organizations, manages a limited set of user, roles, and repository objects and may be overridden by a top-level
organization admin.

1.2 Overview of the Repository

The repository is a hierarchical structure of folders where JasperServer, administrators, and users store resources for creating
reports and doing analysis. In its appearance and function, the repository resembles a file system with a hierarchical structure
of folders that contain resources. Internally, the repository is implemented as a database that is private to the JasperServer
instance.

1.2.1 Folder Structure

The root of the repository tree structure is accessible only to the system admin. It contains the folders for each organization and
folders for certain configuration settings.

Figure 1-1 Root of the Repository Showing Top-Level Organization Folders

Within the repository, each organization has its own branch, contained in a folder named after the organization. JasperServer
automatically restricts users’ view and access to the branch of the repository in their organization’s folder. Organization
admins can create any folder structure needed within the organization.
To mimic the hierarchical structure of organizations, each organization also contains a folder called Organizations where sub-
organizations are created, as shown in section Figure 1-2 on page 10.

1.2.2 Resources
Resources are stored in the repository and used as input for creating reports and performing analysis. Certain resources such as
images, fonts, or JRXML created in iReport are uploaded from files. Others such as data sources and Domains are created
within JasperServer. Of course, reports can also be saved in the repository to be run as often as needed, and output such as PDF
or HTML can be saved in the repository as well.
Each resource has a unique short name, a display name, and an optional description. As in a file system, the names of folders
containing the resource give the path to the object. Users locate resources in the repository by browsing through folders,
searching for keywords, or by filtering resources by type, date, etc. The repository displays the descriptions in listings or in
tooltips to help users understand the contents or purpose of a resource.

9
JasperServer Administrator Guide

Resources are stored in an internal format that is not accessible to users or administrators, although certain objects can be
downloaded to your file system in an output format such as XML. Any repository object may be exported to a file with the js-
export utility, but the resulting files are for backup or transfer to another JasperServer instance and cannot be modified.

JasperServer restricts access to folders and resources based on organizations, user names, and roles. The system admin and
organization admin can define permissions as explained in section 1.3, “Overview of Users and Roles,” on page 11.

1.2.3 Sample Data

When you install the sample data in Jasper Server, the default organization has folders and objects showing typical content in
the repository. As shown in the following figure, the default organization is named Organization.
The sample data includes dashboards, reports, Domains, data sources, and many components used in these, such as input
types, content files, 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 inter-related dashboards, reports, and resources for various business
scenarios within a fictional grocery store company.

System admin view: Organization admin view:

Figure 1-2 System Admin and Organization Admin Views of the Same Sample Data

Every level of the organization hierarchy, including the system or root level, has a folder named Organizations to contain sub-
organizations. The left-hand view in Figure 1-2 shows the root of the Repository, as seen by the system admin. The
Organizations folder at the root contains the main folder for top-level organizations. In the sample data, there is only the
default organization named Organization. The right-hand view in the figure shows the Organization folder, as seen by the
organization admin who has no visibility outside of the Organization folder.
The Organizations folder always contains a folder named Folder Template. When a new organization is created, the entire
contents of Folder Template is copied to a new folder under Organizations and given the name of the new organization. In the
sample data, there is a Folder Template for top-level organizations, and one inside the default organization, for use in creating
sub-organizations. By default, both of these Folder Templates, contain the minimal folder structure required for new
organizations, namely a Topics folder under Ad Hoc Components and a Temp folder. The admin can add any folders or
resources to the Folder Template that will be used in subsequently created organizations.
The Public folder at the root is a special folder shared with all organizations. It is visible to every organization so that the
system admin can share certain resources in common, such as a data source, a company logo image, or a report template.

10
 Introduction to JasperServer Administration

1.3 Overview of Users and Roles

User accounts and role assignments provide authentication and authorization mechanisms to implement access control in
JasperServer. Users enter an organization name, a login name, and a password in order to access JasperServer. Administrators
assign named roles to users and then create role-based permissions to further restrict access to objects in the repository and to
data in Domains.
Both users and roles are associated with the organizations in which they are defined, and they follow the same hierarchical
model. Users and roles defined in an organization may be granted or denied access to any repository folder or object within the
organization or its sub-organizations. However, the administrator of the sub-organization has no visibility of the roles and
users in the parent organization, even if they are used in access permission within the sub-organization.
User names and role names are unique within an organization, but not necessarily among sub-organizations or across all
organizations in JasperServer. For example, the default organization administrator is called jasperadmin in every
organization. Because the organization must be given when logging in, JasperServer can distinguish between every user. In
some cases such as web services, a user is identified by the unique string username|organization_ID.
Access to the repository is defined directly on the repository resources. Administrators may define a level of access, such as
read-write, read-only or no access, and each permission may be based either on a user name or on a role name.
Administrator privileges are determined by system-level roles named ROLE_SUPERUSER and ROLE_ADMINISTRATOR. This
allows several users to be system admins or organization admins for large deployments. Based on the presence of either of
these roles, JasperServer presents the appropriate administrator options in menus, tool bars, and on the user’s home page. For
more information, see section 2.1, “Scope of Administrative Privileges,” on page 15.

1.4 Logging In
The existence of multiple organizations changes how users log in on the welcome page.

1.4.1 Single Organization

In the default or minimal installation, there is a single organization and logging in is exactly the same as in previous versions
of JasperServer. Users must specify a user ID and a password, but they do not need to be aware of the organization structure.

Figure 1-3 Default Login Screen

11
JasperServer Administrator Guide

Administrators log in with this screen as well, using the following default passwords:
Š Username superuser and password superuser for the system admin.
Š Username jasperadmin and password jasperadmin for the organization admin.

For security reasons, always log in and change both administrator passwords immediately after installing
JasperServer. For instructions, see section 2.3, “Managing Users,” on page 19.

1.4.2 Multiple Organizations

When more than one organization exists within JasperServer, even as a sub-organization of a single organization, users must
specify their organization when logging in. To ensure uniqueness, users must enter the ID or alias of the organization, not its
display name. For example, the default organization has the display name Organization, and its ID is organization_1, as
shown on the left of Figure 1-4.

http://<server>:8080/jasperserver-pro/login.html http://<server>:8080/jasperserver-pro/login.html?
orgId=organization_1

Figure 1-4 Alternate Login Screens for Multiple Organizations

To simplify the login for users who are always in the same organization, the organization ID may be specified in the URL of
the login page. When the organization ID is specified in the URL, JasperServer displays the simpler login dialog, as shown on
the right of Figure 1-4. Users can bookmark this URL to avoid entering the organization ID each time.
The system admin, superuser by default, must leave the organization name blank. When logging in as the system admin,
you must clear the Organization name from the login screen or from the login URL. To summarize, administrators log in with
the following credentials:
Š System admin – Organization field or URL blank, username superuser, and password superuser.
Š Organization admin (default organization) – Organization field or URL organization_1, username jasperadmin, and
password jasperadmin. If you have created other organizations, log in with their organization ID or alias, not their
display name.

For security reasons, always log in and change both administrator passwords immediately after installing
JasperServer. For instructions, see section 2.3, “Managing Users,” on page 19.

1.4.3 JasperServer Heartbeat

When you login to JasperServer for the first time after installation, you may be prompted to opt into JasperServer’s Heartbeat
program. The heartbeat reports specific information to Jaspersoft about your implementation: the operating system, JVM,
application server, RDBMS (type and version), and JasperServer edition and version number. By tracking this information,
Jaspersoft can build better products that function optimally in your environment. No personal information is collected; for
more information see http://www.jaspersoft.com/heartbeat.
To opt into the program, click OK. To opt out, clear the check box and click OK.

12
 Introduction to JasperServer Administration

1.5 Administrator Pages

After logging in, administrators see a Getting Started page that has more controls than a standard user’s Getting Started page.
To return to this Getting Started page at any time, click Home on the main menu bar.

Figure 1-5 Getting Started Page for Administrators

Figure 1-5 shows the About JasperServer link in the page footer. This link is available on every page to both users and
administrators and displays the product version number, as shown in the following figure:

Figure 1-6 About JasperServer Dialog

The About JasperServer dialog also shows the software build, your license type, and its expiration. Please have this
information available if you need to contact Jaspersoft for support.
Administrator controls are accessible by clicking manage the app to open the Manage page or directly through the Manage
menu in the main menu bar.

13
JasperServer Administrator Guide

Figure 1-7 Admin Home Page for System Admins

All possible administrator controls are available to the system admin. They include managing organizations, users, and roles,
as well as configuration options for analysis and the Ad Hoc Editor. For more information about the Ad Hoc settings, see
section 5.3, “Ad Hoc Configuration,” on page 47.

Figure 1-8 Admin Home Page for Organization Admins

The organization admin is limited to managing the organizations, users, and roles of her organization and cannot access any
system configuration.

As shown in the figures above, certain administrator controls are available only through the Manage menu, notably
Manage > Organizations.

14
 Organization, User, and Role Management

2 ORGANIZATION, USER, AND ROLE MANAGEMENT

Administrators use the management interface to create the organizations in their deployment, if any, populate them with users,
and assign roles that they can later use to enforce access permissions to the repository. In the default, single organization
deployment, the administrator only needs to create users and roles.
In a deployment with multiple organizations, there can be administrators at every level of the hierarchy, as described in
section 1.1.3, “Delegated Administration,” on page 8. Part of any large deployment is to designate which administrators are
responsible for each specific task. For example, system administrators might set up the top-level organizations and default
roles, but each organization’s admin would then create and manage the users of that particular organization.
The interface in JasperServer for managing organizations, users, and roles accommodates all levels of administrators and
makes it easy for them to find hundreds of users and roles, whether in a single organization or spread across many. The
interface also enforces the scope of administrative privileges, for example so that an administrator can never see a role or user
from a parent organization.
This chapter contains the following sections:
Š Scope of Administrative Privileges
Š Managing Organizations
Š Managing Users
Š Managing Roles

2.1 Scope of Administrative Privileges

Organization admins have the ability to:
Š Create sub-organizations.
Š Create, modify, and delete users, including changing their password. However, no administrator can ever view a user’s
existing password in clear text.
Š Login as any user in the organization for testing system access.
Š Create, modify, and delete roles.
Š Assign roles to users, including the ROLE_ADMINISTRTOR role that grants organization admin privileges.
Š Create, modify, and delete folders and repository objects of all types.
Š Set access permissions on repository folders and objects.
System admins have the ability to:
Š Perform all organization-level tasks listed above, on any organization within the system.
Š Create top-level organizations.

15
JasperServer Administrator Guide

Š Create users outside of organizations that can access all organizations.

Š Assign the ROLE_SUPERUSER role that grants system admin privileges.
Š Set the system-wide configuration parameters.
For delegated administration, an existing administrator may grant these privileges to any user. There are three factors that
determine the scope of a user’s administrative privileges:
Š ROLE_ADMINISTRATOR – JasperServer confers the organization-level privileges listed above to any user with this role.
When a user with this role logs in, JasperServer displays the additional controls to access the admin pages.
Š The user’s organization – Regardless of roles, an administrator is always limited in scope to the organization in which the
user account is created, including any sub-organizations thereof. In no case can a user, even with the ROLE_SUPERUSER,
ever view or modify any organization, user, or repository object outside of the organization to which the user belongs.
The default system admin user, named superuser, exists at the system level, outside of any organization. This is what
allows the system admin to access any organization and create other system admin users outside of any organization.
Š ROLE_SUPERUSER – When a user already has ROLE_ADMINISTRATOR, this additional role grants access to the system
configuration functions. In a multi-organization environment, this role should not be given to organization admins,
because system configuration includes the Ad Hoc cache shared by all organizations. In the case of a single organization
such as in the default installation, giving this role to the organization admins grants access to system settings without
granting privileges to create top-level organizations or other system administrators.
In order to delegate system administration, the existing system admin must first create other users at the root level, outside of
any organization. The system admin can then assign both ROLE_ADMINISTRATOR and ROLE_SUPERUSER to grant them
system admin privileges. For further information about these roles, see section 3.2, “Access Control,” on page 33.

2.2 Managing Organizations

System admins and organization admins use the same interfaces for managing organizations, the only difference is that system
admins can manage top-level organizations, whereas organization admins are limited to sub-organizations.

Administrators of deployments with a default single organization can generally skip this section. However, this
procedure can be used to change the display name of the default organization.

To create, modify, or delete organizations:

1. Log in as a user with administrative privileges.
2. Select Manage > Organizations and select the organization you want to manage.
The Details frame on the right shows the display name, organization ID and description of the organization selected in the
tree. It also shows the number of users and roles defined in the selected organization and all of its sub-organizations.

Figure 2-1 Manage Organizations Interface Seen by System Admins

16
 Organization, User, and Role Management

This interface includes all the controls for adding, editing, or deleting organizations. For convenience, there are also links
to the interfaces for managing users and roles. All controls operate on the organization that is currently selected in the
hierarchy of organizations.
Figure 2-1 above shows that the system admin can manage any organization or sub-organization in JasperServer. The tree
view on the left shows the hierarchy of organizations starting with the one to which your user belongs. The system admin
does not belong to any organization, and the container for all top-level organizations is called root.

Figure 2-2 Manage Organizations Interface Seen by Organization Admins

Figure 2-2 shows how an organization admin is limited to managing his own organization hierarchy. In this case, the
admin of the Finance organization cannot access the HR or Operations organizations. Also, the Delete Organization
button is inactive when the admin’s own organization is selected.
3. To create a new organization, select the intended parent organization in the hierarchy, then click Add Organization....
The Add Organization dialog appears.

Figure 2-3 Add Organization Dialog

4. Enter the following information for the new organization:

17
JasperServer Administrator Guide

Š The organization name is the display name of the organization. This name appears in the administration dialogs and
on the organization’s folder in the Repository.
Š The organization ID must be unique across all organizations. The dialog suggests an ID based on the organization
name you enter, but you may enter any unique value. The ID cannot be changed after the organization is created. The
organization ID appears in the login URL for users of this organization, as described in section 1.4, “Logging In,” on
page 11.
Š The organization alias is the name of organization that users can enter when logging in. It must also be unique among
all organizations, but it can be modified at any time.
Š The description is a short text describing the organization. The description is displayed to admins on the Manage
Organizations interface.
The text under each field explains any character restrictions within each value.
5. Click Create to create the organization.
The organization appears in the hierarchy on the left and can be further modified if necessary. New organizations contain:
Š No roles – The ROLE_ADMINISTRATOR and ROLE_USER are inherited from the system.
Š jasperadmin and joeuser – Two default users with default passwords.

For security reasons, always change both passwords immediately after creating new organizations. For
instructions, see section 2.3, “Managing Users,” on page 19.

Š A folder under the parent’s Organizations folder in the repository – The new folder has the organization’s display
name and contains a copy of the parent organization’s Folder Template folder.
6. To edit an organization’s information, select the organization in the hierarchy, then click Edit.
In the details frame on the right, the organization name and description become editable, with explanation text under each.
Changing the organization name changes the name of the main organization folder, the one that all organization users see
at the root of their view of the repository. The organization ID cannot be modified, it always has the value defined when
the organization is created. You can change the organization alias if you want to change the value that users enter when
they log in.

Figure 2-4 Edit Organization Dialog

7. Click Save to keep any changes or Cancel to quit without saving your changes.
8. To delete an entire sub-organization, select the organization in the hierarchy, then click Delete Organization. You cannot
delete the organization to which your admin user belongs. When you confirm the deletion, all users, roles, folders of the
organization and any sub-organization it contains are removed from JasperServer.

18
 Organization, User, and Role Management

2.3 Managing Users

As with organizations, all admins use the same interface to manage users in their respective organizations. The only difference
is that system admins can manage all users in all organizations, as well as create users outside of organizations, as described in
2.1, “Scope of Administrative Privileges,” on page 15.
The default installation of JasperServer contains the following users:

User Name Default Password Organization Name Description

superuser superuser none Default system admin

anonymousUser anonymoususer none Allows anonymous login, which is

disabled by default

jasperadmin jasperadmin Organization Default organization admin in every

organization

joeuser joeuser Organization Default end user in every organization

demo demo Organization Included for use with sample data

CaliforniaUser CaliforniaUser Organization Included for use with sample data

Passwords are case sensitive. You should exercise the necessary security precautions, including changing your password
regularly. To configure password policies, refer to section 5.1, “Configuring Password Options,” on page 46.

To create, modify, or delete users:

1. Log in as an administrator for the organization to which the users belong.
2. Select Manage > Users or click users on the administrator’s Manage page.
As shown in the following figure, the Manage Users interface displays the users in the organizations over which you have
administrative privileges. The organization to which your user belongs is selected at the root of the organizations
hierarchy, and the list of users shows all user names in all sub-organizations.

Figure 2-5 Manage Users Interface

If there are many users, the list of users has a scroll bar and paging controls at the bottom. Scroll and click Next and
Previous when necessary to see the entire list of users.

19
JasperServer Administrator Guide

Users are listed alphabetically, and multiple users with the same username may appear. In the figure above, several
organization have been created, and each has a jasperadmin user. A tooltip shows each user’s full name and organization.
To distinguish between organizations, the tooltip shows the hierarchy of organization names relative to your organization,
for example Organization.Finance.Audit in the figure.
3. To narrow the list of users or find a specific user, click on an organization, enter a search string, or both.
This list of users shows all users within the selected organization or any of its sub-organizations and whose username
contains the search string. Scroll and page through the new list, or refine your search.
4. Click on a username in the list of users at any time to see information about the user.
The details frame shows the username, display name, email address and roles if any. Profile attributes are special user
attributes that may only be added through the database and not through the Manage Users interface. The frame also shows
the status of the user, either enabled or disabled. Disabled users also appear in gray in the list of users.
As the admin of a given organization, you only see the roles defined in your organization or any sub-organization.
Except for certain special system-wide roles, any roles of parent organizations are not visible on a user. For more
information, see section 2.4, “Managing Roles,” on page 22.

This frame includes all the controls for editing, logging in as, or deleting the selected user. For convenience, there are also
links to manage each role.
5. To create a new user, select the desired organization in the hierarchy, then click Add User in the top-right corner. Admins
can create a user within their own organization or any sub-organization.
The Add User dialog appears.

Figure 2-6 Add User Dialog

6. Enter the following information for the new user:

Š The user ID is the username or login name. This name is used throughout JasperServer to identify the user. User IDs
must be unique within an organization, but not necessarily among its sub-organizations or any other organization.
The dialog warns you if the user ID you enter is not unique within the chosen organization. The text under this field
explains the character restrictions within the user ID.
Š The full name of the person. This optional name can be in any format or convention. JasperServer displays this name
in the top right-hand corner of the screen for each user.
Š The email address of the person. The email is optional but the address must be in a valid format.
Š Password and confirmation. Enter the user’s default password in each field.
Š Select the checkbox to enable the user right away. If a user account is not enabled, the person cannot log in with this
username. For example, you may not want to enable the user account until you have assigned its roles.
7. Click Submit to create the user.

20
 Organization, User, and Role Management

The new user is selected in the list of users unless you have entered a search term that does not include the new user.
Review the details of the user you just created. JasperServer automatically assigns the ROLE_USER to every new user.
8. To edit a user, find the user by searching or selecting an organization, click on the username in the list of users, then click
Edit in the details frame on the right.
In the details frame, the user details become editable, except for the user ID and the profile attributes. The user ID cannot
be modified, it always has the value defined when the user is created. The profile attributes can only be modified in the
database, not through the Manage Users dialog.

Figure 2-7 Edit User Dialog

9. To change the roles that are assigned to the user, click edit roles.
The Edit Roles dialog appears for the user that you are editing.

Figure 2-8 Edit Roles Dialog

The list on the right displays the roles currently assigned to the user. To remove roles, select one or more roles in the right-
hand list and click the left arrow button. The list on the left displays all other roles that may be assigned to the user. To
assign roles, select one or more roles in the left-hand list and click the right arrow button. The available roles include any
role in the organization of the user, any role in a parent organization of the user up to and including the organization of the
current administrator, and the special system-wide roles. When finished assigning roles, click Done.
10. When done modifying any user fields or roles, you must click Save to keep any changes.
11. Click Log in as User to test the user’s permissions, as explained in 3.2.5, “Testing User Permissions,” on page 38.

21
JasperServer Administrator Guide

Another reason to log in as another uses is when creating and maintaining resources that use absolute references in the
repository. The system admin creates absolute references that are not accessible to users within organizations. The system
admin must log in as the admin of the organization that want to use the resource so that it is created with an absolute
reference that is valid in the context of the organization. For more information, see section 3.3.2, “Referencing
Resources in the Repository,” on page 39.
12. To delete a user, locate and select the user, then click Delete User.
When you confirm the deletion, the user is removed from JasperServer.

2.4 Managing Roles

Roles define sets of users who are all granted similar permissions. Roles are created by administrators, assigned to users, and
then assigned permissions in the repository. By default, JasperServer includes the following roles; some are needed for system
operation, some are included as part of the sample data:

Role Description
ROLE_SUPERUSER This role determines system admin privileges, as explained in section 2.1, “Scope
of Administrative Privileges,” on page 15. It is a system-level role, however the
system admin may assign it to organization admins in single-organization
deployments.

ROLE_ADMINISTRATOR This role determines organization admin privileges, as explained in section 2.1,
“Scope of Administrative Privileges,” on page 15. JasperServer automatically
assigns this role to the default jasperadmin user in every new organization. It is a
special system-level role that is visible in every organization and which
organization admins may assign to other users.

ROLE_USER Every user that logs into JasperServer must have this role. JasperServer
automatically assigns this role to every user that is created, and it cannot be
removed. It is a special system-level role that is visible in every organization.

ROLE_ANONYMOUS When anonymous access is enabled, JasperServer automatically assigns this role
to any agent accessing JasperServer without logging in. This role is also assigned
to the default anonymous user. By default, anonymous access is disabled and this
role isn’t used. It is a special system-level role that is visible in every organization.

ROLE_PORTLET JasperServer assigns this role to users that are created automatically when a
portal such as Liferay requests authentication for a connection. If the specified
user name does not exist in JasperServer, it is created, assigned the password of
the user in the portal, and assigned the ROLE_PORTLET and ROLE_USER roles.

ROLE_DEMO This role grants access to the SuperMart demo Home page, reports, and if you
implement JasperAnalysis, analysis views. This role is assigned to the demo user
in the default organization. These objects are available only if you installed the
sample data when you installed JasperServer. It is a special system-level role that
is visible in every organization.

ROLE_SUPERMART_MANAGER This role is used to assign permissions relative to the sample data. It is a special
system-level role that is visible in every organization. It demonstrates data security
features available in JasperAnalysis. See the JasperAnalysis Ultimate Guide for
more information.

ROLE_ETL_ADMIN This role no longer governs any JasperServer permissions or functionality, unless
it has been customized in your installation. Typically, it can be deleted safely.

Except for the five special system-level roles visible in every organization, roles are defined in organizations. As with users,
the same role ID can be defined in separate organizations, as long as it is unique within any given organization. Similarly, roles
are visible only within the organizations that define them. Admins may see all roles within their organization and sub-
organizations, but never any roles from a parent or sibling organization. Even if the admin of the parent organization has

22
 Organization, User, and Role Management

assigned the role to a user in a sub-organization, the admin of the sub-organization sees the user without the parent role. The
interface for managing roles enforces this scoping, so that only valid roles may be assigned to any given user.
The interface for managing roles lets you create roles and assign each role to many users. If you want to assign several existing
roles to a single user, see section 2.3, “Managing Users,” on page 19.

To create, modify, delete, or assign a role to users:

1. Log in as an administrator.
2. Select Manage > Roles or click roles on the administrator’s Manage page.
As shown in the following figure, the Manage Roles interface displays the roles in the organizations over which you have
administrative privileges. The organization to which your user belongs is selected at the root of the organizations
hierarchy, and by default, the list of roles shows all roles in all sub-organizations. The five special system-level roles are
also listed in every organization.

Figure 2-9 Manage Roles Interface

If there are many roles, the list of roles has a scroll bar and possibly paging controls at the bottom. Scroll and click Next
and Previous when necessary to see the entire list of roles.
Roles are listed alphabetically, and multiple roles with the same name may appear. A tooltip shows the organization in
which each role is defined, relative to your organization.
3. To narrow the list of roles or find a specific role, click on an organization, enter a search string, or both.
This list of roles shows all roles within the selected organization or any of its sub-organizations and whose name contains
the search string. Scroll and page through the new list, or refine your search.
4. Click on a role name in the roles list at any time to see information about the role.
The details frame shows the role name, the organization where it is defined, and the list of users to whom the role has been
assigned. Tooltips on the usernames help you distinguish among users with the same name.
This frame includes the controls for editing or deleting the selected role. For convenience, there are also links to manage
each organization or user that is referenced.
Unless you are logged in as the system admin, you cannot edit or delete the five special system-level roles.
Furthermore, when you view the details of the special system-level roles, you only see the users defined in your
organization or any sub-organization to which this role has been assigned. For more information, see the table at
the beginning of section 2.4, “Managing Roles,” on page 22.

5. To create a new role, select the desired organization in the hierarchy, then click Add Role in the top-right corner. Admins
can create a role within their own organization or any sub-organization.
The Add Role dialog appears.

23
JasperServer Administrator Guide

Figure 2-10 Add Role Dialog

6. Enter a name for the new role. The text under the field explains the character restrictions in role names. The dialog warns
you if the name you enter is not unique within the chosen organization. Roles have no other properties or settings.
7. Click Submit to create the role.
The new role is selected in the list of roles unless you have entered a search term that does not include the new role name.
8. To edit a role name or assign the role to users, find the user by searching or selecting an organization, click on its name in
the list of roles, then click Edit in the details frame on the right.

Figure 2-11 Edit Role Dialog

In the details frame, the role name becomes editable. Changing the name of an existing role affects all users to which the
role is assigned. The role name associated with permissions in the repository is also updated automatically.

However, changing a role name may compromise permissions defined in security files for Domains and analysis.
For more information, see the JasperServer User Guide.

9. To change the list of users to which the role is assigned, click change....
The Assign Users dialog appears for the role that you are editing.

24
 Organization, User, and Role Management

Figure 2-12 Assign Users Dialog

The list on the right displays the users to which the role is currently assigned. To remove users, select one or more user
names in the right-hand list and click the left arrow button. To assign the role to these users, select one or more users in the
left-hand list and click the right arrow button.
The list on the left displays all other users to which the role may be assigned. The eligible users that are displayed include
any user in the organization where the role is defined or its sub-organizations. This list may be quite long and include
duplicate names, as shown for a different example in Figure 2-13. Use the search field to find specific user names, and
use the tool tips to differentiate between users.

Figure 2-13 Searching on the Assign Users Dialog

When finished assigning the role to users, click Done.

10. When done modifying the role, you must click Save to keep any changes.
11. To delete a role, locate and select the role, then click Delete Role.
When you confirm the deletion, the role is removed from JasperServer.

25
JasperServer Administrator Guide

26
 Repository Administration

3 REPOSITORY ADMINISTRATION

The repository stores content files, data sources, datatypes, images, saved reports, and any other resource in JasperServer. The
repository is structured as a hierarchy of folders that is based on the hierarchy of organizations. For more information, see
sections 1.2.1, “Folder Structure,” on page 9 and 1.2.3, “Sample Data,” on page 10. Administering the JasperServer
repository includes the following tasks:
Š Creating folders and organizing repository objects.
Š Controlling access to objects in the repository using roles, users, and object-level permissions.
Š Managing references to data sources, images, fonts, and other resources upon which reports rely.
This chapter contains the following sections:
Š Managing Folders and Resources
Š Access Control
Š Multiple Organizations in the Repository

3.1 Managing Folders and Resources

Administrators and users with the proper permissions can create, modify, move, and delete folders and resources within the
repository.
The specific roles and permissions of the user determine what actions are available. The following sections explain what
permissions are necessary to perform each action. When an action creates a resource, the section also gives the initial
permissions assigned to the resource. For the definition of the permissions on folders and resources, see section 3.2.3,
“Permissions,” on page 35.
Within the repository and search results view, all actions on folders and resources are accessible through their context menu.
Right-click on the folder or resource name to see the context menu for that object. Use any combination of search, folder
browsing, or filters to display the resources you want to operate on.

3.1.1 Creating a New Folder

Any user with write permission on a folder can create new folders within it. By default, a new folder and its future contents
inherit all permissions from the parent folder.
1. Log on as a user who has write permission to the parent folder.
2. Click View > Repository and locate the folder in which you want to create the new folder.

27
JasperServer Administrator Guide

3. Right-click the parent folder and select Add Folder from the context menu .

4. Enter a folder name and an optional description in the dialog that appears, then click Add.
The folder is created in the repository.

3.1.2 Adding Resources to the Repository

Only administrators can add resources to the repository. Regular users, even those with write permission on a folder, cannot
create resources. By default, a new resource inherits all permissions from its parent folder.
1. Log on as an administrator.
2. Click View > Repository and locate the folder in which you want to create the new resource.
3. Right-click the parent folder and select Add Resource from the context menu. Then select the type of resource to add.
The most common object types, such as reports and images, appear on the Add Resource menu. Less common object
types are listed on the Other menu at the bottom of the Add Resource menu.

Figure 3-1 Add Resource > Other Menu

4. Enter the information in the resource creation wizard specific to the resource you chose.
Some resources are based on uploaded files, others on information you enter in the dialog. All wizards include fields to
specify an object name, display name, and description in the repository. The object name is a unique name within the
folder. The display name and description appear to users in the repository.
If you are creating a data source, click Test Connection to have JasperServer validate it. If the test fails, review the values
that you specified in the other fields and test the data source again.
5. After you enter all the requested information, click Save.
The resource is created and added to the repository.
For more specific procedures to create reports, domains, and data sources, refer to the JasperServer User Guide. For
information about creating analysis views and OLAP client connections, refer to the JasperAnalysis User Guide.

3.1.3 Renaming a Folder or Resource

Any user with write permission on a folder or resource can change its display name or description.

28
 Repository Administration

You cannot change the name of an organization’s main folder through the repository. The name of the main folder is
always the display name of the organization. To change the name of the main folder, change the display name of the
organization, as described in section 2.2, “Managing Organizations,” on page 16.

1. Log on as a user who has write permission to the folder or resource.

2. Click View > Repository and locate the folder or resource you want to change.
3. Right-click the folder or the resource you want to change and select Properties... from the context menu.
4. In the dialog that appears, enter a new display name or description:

Figure 3-2 Resource Properties Dialog for a Writable Resource

Users cannot modify the resource type or the resource ID; these are internal fields displayed for information only. Users
with administer permissions can change the user access settings as described in section 3.2.4, “Assigning Permissions,”
on page 36.
5. Click OK to make the change.

3.1.4 Viewing a Report or Dashboard

Only reports and dashboards support a viewing mode, which is equivalent to running the report or dashboard with current data.
The report can be either a JRXML report uploaded by an administrator or an Ad Hoc report saved in the repository. Any user
with read permission can view (run) a report or dashboard.
1. Log on as a user who has read permission to the report or dashboard.
2. Click View > Repository and browse or search for the report or dashboard you want to view.
3. Click the name of report or dashboard to run it. Alternatively, right-click the report or dashboard and select View from the
context menu.
The report or dashboard begins to run, and an activity monitor appears until the report or dashboard contents are
displayed. The longer or more complex the report or dashboard is, the more time it takes to display.
4. If you selected a long report by accident and it takes too long to display, click Cancel in the activity monitor.
5. To return to the repository or search results page:

Š From a report, click the back icon or click View > Repository.
Š From a dashboard, click View > Repository or click your browser’s back button.
For detailed procedures about running reports and dashboards, refer to the JasperServer User Guide.

3.1.5 Modifying an Ad Hoc Report or Dashboard

Users with write permissions can open Ad Hoc reports and dashboards in the Ad Hoc Editor or dashboard designer,
respectively. They can then modify the report or dashboard, overwrite the original, or save it as a new one. Ad Hoc reports and
dashboards are the only resources whose content can be modified by end-users. All other resources such as JRXML reports
and Domains can only be modified by administrators, as described in section 3.1.6, “Editing a Resource,” on page 30.

29
JasperServer Administrator Guide

1. Log on as a user who has write permission to the report or dashboard.

2. Click View > Repository and browse or search for the report or dashboard you want to modify.
3. Right-click the Ad Hoc report or dashboard and select Open in Designer... from the context menu .

Ad Hoc reports open in the Ad Hoc Editor and dashboards open in the dashboard designer. For detailed procedures about
working in the Ad Hoc Editor and the dashboard designer, refer to the JasperServer User Guide.
4. When you save your Ad Hoc report or dashboard, it overwrites the original one. In the Ad Hoc Editor, choose Save As to
save a new report and preserve the original.
5. To return to the repository or search results page after saving your work:
Š From the Ad Hoc editor, click View > Repository or click your browser’s back button.
Š From the dashboard designer, click Cancel or click View > Repository.

3.1.6 Editing a Resource

Editing a resource invokes the same wizard used to define the resource when it was created. When editing the definition of a
resource, you can reload a file, for example, or change a setting. Editing a resource can also be useful to view its settings, even
if you don’t want to modify them.
Resources that have been created through the Add Resource menu can only be edited by administrators. For example, only an
administrator can edit a JRXML report that he, or another administrator, previously uploaded to the repository. Administrators
can also edit the report unit of an Ad Hoc report. Regular users, even those with write permission on a resource, cannot edit the
definition of repository resources.
1. Log on as an administrator.
2. Click View > Repository and search or browse for the resource you want to edit.
3. Right-click the resource, then select Edit from the context menu .

4. Use the dialog specific to the resource to view or modify it’s definition or properties.
5. To return to the repository without changing the resource, click Cancel in the wizard. When modifying a resource, click
OK or Save to make the changes permanent.

3.1.7 Copying Folders or Resources

Any user with read permission can copy folders and resources in the repository, as long as the user has write permission on the
target folder where the copy is made. When copying a folder, all the resources and folders it contains are copied recursively as
well.

When copying a folder or resource, permissions are not preserved and the new copy inherits all permissions from its
parent folder. Administrators must explicitly set permissions again after making copies of folders or resources.

30
 Repository Administration

Copying is available through drag-and-drop as well as from context menus using the copy-paste model. Folders must be
copied individually, but resources can be copied in bulk.

To copy folders or resources by drag-and-drop:

1. Log on as a user who has read permission to the folder or resource.
2. Click View > Repository and locate the folder or resources you want to copy.
3. Select the folder or resource so that it is highlighted. For resources such as reports whose names are active links, check the
box beside the name or click anywhere in the row to select it.
To copy more than one resource at a time, select all the ones you want to copy with Control-click or check the box beside
each resource.
4. Press Control while you drag the highlighted folder or resources and drop them on a folder for which you have write
permission.
While dragging, the mouse pointer changes to show you are copying a folder, a resource, or multiple resources. It also
changes to show that certain folders such as the top organization folder are not valid targets. The mouse pointer does not
indicate whether you have write permission on the target folder. If you drop the objects on a folder for which you do not
have write permission, the objects are not copied.
To cancel the copy operation, drop the object in a blank area of the repository.
5. If you have write permission to the target folder, the folder or resources are copied, and the repository display updates to
reflect the new contents, according to your current search and filter settings.

To copy folders or resources using context menus

1. Log on as a user who has read permission to the folder or resource.
2. Click View > Repository and locate the folder or resources you want to copy.
3. Right-click the folder or resource and select Copy from the context menu .

To copy more than one resource at a time, select all the ones you want to copy with Control-click or check the box beside
each resource name, then click Copy above the list of resources.

In both cases, the mouse pointer changes to indicate you have initiated a copy operation.
4. Right-click the destination folder and select Paste from the context menu .

If Paste does not appear in the context menu of a folder, you do not have write permission there.
To cancel the copy operation, right-click any folder and select Cancel.
5. After selecting Paste, the folder or resources are copied, and the repository display updates to reflect the new contents,
according to your current search and filter settings.

3.1.8 Moving Folders or Resources

Users with write permission can move folders and resources in the repository, as long as they have write permission on the
target folder as well. When moving a folder, all the resources and folders it contains are moved as well.

Moving a folder or resource preserves any permissions that were explicitly defined. Any permissions that were
inherited from its parent folder are inherited from the new parent after the move, and thus can potentially change.

31
JasperServer Administrator Guide

Moving is available through drag-and-drop, as well as from context menus using the cut-and-paste model. Folders must be
moved individually, but resources can be moved in bulk operations.

To move folders or resources by drag-and-drop:

1. Log on as a user who has write permission to the folder or resource.
2. Click View > Repository and locate the folder or resources you want to move.
3. Select the folder or resource you want to move so that it is highlighted. For resources such as reports whose names are
active links, check the box beside the name or click anywhere in the row to select it.
To move more than one resource at a time, select all the ones you want to move with Control-click or check the box
beside each resource.
4. Drag the highlighted folder or resources and drop them on a folder for which you have write permission.
While dragging, the mouse pointer changes to show you are moving a folder, a resource, or multiple resources. It also
changes to show that certain folders such as the top organization folder are never valid targets. The mouse pointer does
not indicate whether you have write permission on the target folder. If you drop the objects on a folder for which you do
not have write permission, the objects are not moved.
To cancel the move operation, drop the object in a blank area of the repository.
5. If you have write permission to the target folder, the folder or resources are moved, and the repository display updates to
reflect the new location, according to your current search and filter settings.

To move folders or resources using context menus

1. Log on as a user who has write permission to the folder or resource.
2. Click View > Repository and locate the folder or resources you want to move.
3. Right-click the folder or a single resource, and select Cut from the context menu .

To move more than one resource at a time, select all the ones you want to move with Control-click or check the box
beside each resource name, then click Cut above the list of resources.

In both cases, the mouse pointer changes to indicate you have initiated a move operation.
4. Right-click the destination folder and select Paste from the context menu .

If Paste does not appear in the context menu of a folder, you do not have write permission there.
To cancel the move operation, right-click any folder and select Cancel. The selected folder or resources will not be cut.
5. After selecting Paste, the folder or resources are moved, and the repository display updates to reflect the new location,
according to your current search and filter settings.

3.1.9 Deleting Folders or Resources

Users with delete permission on a folder or resource can delete those objects from the repository. In order to delete a folder,
the user must have delete permission on all the resources and folders it contains, recursively.

32
 Repository Administration

The repository keeps track of which resources are referenced by other resources, and does not allow you to delete
them while they are still being referenced. For example an input type that is used by a report or a properties file that is
used by a Domain cannot be deleted as long as the report or Domain still reference them.
To find the resources that reference the one you want to delete, you need to look at each report, Ad Hoc topic, or
Domain that you suspect of referencing it. When you edit a JRXML report or open a Domain in the Domain designer,
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.

Folders must be deleted individually, but resources can be deleted in bulk:

1. Log on as a user who has delete permission to the folder or resource.
2. Click View > Repository and locate the folder or resources you want to delete.
3. Right-click the folder or a single resource, and select Delete from the context menu .

To delete more than one resource at a time, select all the ones you want to delete with Control-click or check the box
beside each resource name, then click Delete above the list of resources.

4. Confirm that you want to delete the folder or resource.

There is no undo.

3.2 Access Control

Access control ensures that people using JasperServer can only access the data they are allowed to see. JasperServer provides
access control through an integrated security framework that includes:
Š Authentication – Restricts access to identified users and protects that access with passwords. Defines roles for grouping
users and assigning permissions. For more information, see section 3.2.1, “Authentication Overview,” on page 33.
Š Authorization – Controls access to repository objects, pages, and menus based on users and roles. Described in
section 3.2.2, “Authorization Overview,” on page 34 and subsequent sections.
Š Data level security – Defines row and column level permissions to access your data. Row and column level permissions
can be defined and enforced in Domains. For more information, refer to the JasperServer User Guide. If you implement
JasperAnalysis, you can use roles to secure your data at any level of an analysis schema’s hierarchy. For more
information, refer to the JasperAnalysis User Guide.

3.2.1 Authentication Overview

The first part of security is to define user accounts and secure them with passwords. Users must log in with their user ID and
password so that they have an identity within JasperServer. JasperServer stores user definitions, including encrypted
passwords, in a private database. Administrators create, modify, and delete user accounts through the administrator pages, as
described in section 2.3, “Managing Users,” on page 19.
JasperServer also implements roles that can be assigned to any number of users. Roles let administrators create groups or
classes of users that are granted certain permissions. For example, administrator privileges are granted by the role named
ROLE_ADMINISTRATOR. A user may belong to any number of roles and receive the privileges from each of them.
JasperServer stores role definition in its private database, and administrators create, modify, and delete roles through the
administrator pages, as described in section 2.4, “Managing Roles,” on page 22.
JasperServer relies on the open source Acegi security framework; it has many configurable options for:

33
JasperServer Administrator Guide

Š External authentication services such as LDAP (used by Microsoft Active Directory and Novell eDirectory)
Š Single sign-on using JA-SIG's Central Authentication Service (CAS)
Š Java Authentication and Authorization Service (JAAS)
Š Container security (Tomcat, Jetty)
Š SiteMinder
Š Anonymous user access (disabled by default)
JasperServer also supports these encryption and authentication standards:
Š HTTPS, including requiring HTTPS
Š HTTP Basic
Š HTTP Digest
Š X509
The Acegi framework is readily extensible to integrate with custom and commercial authentication services and transports.
Authentication occurs by default through the web user interface, forcing login, and/or through HTTP Basic authentication for
web services, such as iReport and for XML/A traffic. JasperServer can automatically synchronize with an external
authentication service. The external users don’t need to be created manually in JasperServer first. Both users and roles are
created automatically in JasperServer from their definitions in an external authentication service. For an overview of the
authentication system and details about external authentication, see the External Authentication Cookbook.

3.2.2 Authorization Overview

With a user’s identity and roles established, JasperServer controls the user’s access in several ways:

Menu Options and The menus that appear in JasperServer depend on the user’s roles. For example, only users
Pages with the administrator role can see the Manage menu and access the administrator pages.
By modifying JasperServer’s configuration, you can modify access to menus, menu items,
and individual pages. Refer to the JasperServer Source Build Guide and JasperServer
Ultimate Guide for more information.

Organization Scope Users belong to organizations and are restricted to seeing resources within their
organization. Organizations have their own administrators, but they see only the users,
roles, and resources from their organization. When JasperServer is configured with multiple
organizations, they are effectively isolated from each other. For more information, see
section 3.3, “Multiple Organizations in the Repository,” on page 38.

Resource Administrators can define access permissions on every folder and resource in the
Permissions repository. Permissions are defined for every role and every user, or they can be left
undefined so they are inherited from the parent folder. For example, user may have read-
write access to a folder where they create reports, but the administrator can also create
standard reports in the same folder that are set to read-only.
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. Permission levels are explained in section 3.2.3, “Permissions,” on
page 35.

Administrator JasperServer distinguishes between reading or writing a resource in the repository and
privileges viewing or editing the internal definition of a resource. For security purposes, granting a user
read or write permission on a resource does not allow viewing or editing the resource
definition. For example, users need read permission on a data source to run reports that use
it, but they cannot view the data source’s definition which includes a database password.
Only administrators can create, view, or edit the definition of a resource and its internal
components.

Data-level security Data-level security defines what data can be retrieved and viewed in a report, based on the
username and roles of the user who runs the report. For example, a management report
could allow any user to see the management hierarchy, managers would see the salary
information for their direct employees, and only human resource managers would see all
salary information.
Data-level security in Domains is explained in the JasperServer User Guide. Data-level
security through analysis views is covered in the JasperAnalysis User Guide.

34
 Repository Administration

3.2.3 Permissions
Permissions on folders and resources determine what users see in the repository and what actions they are allowed to perform.
In the following table, the actions granted for each permission include all of the actions granted for permissions above it,
except for the No Access permission. The actions granted for each permission strictly exclude all of the actions granted for
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 or indirectly.

Read Only Š See the folder or resource in any JasperServer dialog

Š 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 dashboard
Š 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 + Delete Š Add a subfolder

Š Paste into a folder (copy or cut)
Š Save a new Ad Hoc report or dashboard in a folder
Š Save the output of a scheduled report in a folder
Š Rename a folder or resource and change its description string
Š Open an Ad Hoc report in the Ad Hoc editor or a dashboard in the designer
Š Modify and overwrite an existing Ad Hoc report or dashboard

Administer Š Set the permissions (by role and by user) of a folder or resource

Administer and ROLE Š Add (create) a resource in a folder

_ADMINISTRATOR Š Edit a resource (for example, the components of a report unit or a Domain)

Permissions apply to access when browsing or searching the repository, as well as any dialog that accesses the repository, such
as when 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 section 3.1.7, “Copying Folders or Resources,” on page 30.
Š Copying and cutting (moving) actions can only be completed if the user has Read + Write + Delete access to a folder in
which to paste the objects. For more details, see section 3.1.8, “Moving Folders or Resources,” on page 31.
Š 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 or the contents of a folder is only allowed if no other resources rely on them. For more details, see
section 3.1.9, “Deleting Folders or Resources,” on page 32.

3.2.3.1 Inheriting Permissions

According to the permission architecture, there is a permission setting for every user and role on every folder and resource in
the repository. To simplify the definition of permissions, JasperServer supports the inheritance of permissions from the parent
folder of 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.

35
JasperServer Administrator Guide

Using this mechanism, administrators can manage large hierarchies of content and keep them secure. When the administrator
sets 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. Permissions that are assigned on an organization’s top folder
are inherited across the entire organization. Permissions that are set on the root folder or Organizations folder by the system
admin are inherited across multiple organizations.
For example, the system admin can make all organizations read-only by default to ordinary users, and each organization admin
can make specific folders writable so that users can store their reports and output.

3.2.3.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. Therefore, for every folder or resource, every user has a their own user-based permission and the
permission assigned to the ROLE_USER.
How does JasperServer determine the effective permission from the many that apply? Permissions in JasperServer 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 Read-Only applies, regardless of whether it is
inherited or set explicitly.

3.2.3.3 Administrator Permissions

The JasperServer authorization architecture distinguishes between administrators and all other users. Administrators are
defined as users with either ROLE_SUPERUSER, ROLE_ADMINISTRATOR, or both. By design, system administrators
with the ROLE_SUPERUSER always have irrevocable Administer access to the entire repository, including to the contents of
every organization. The system administrator cannot modify the permissions for ROLE_SUPERUSER, to prevent being
locked out or unable to administer some resource. Therefore, the system admin can set permissions for all other users, on any
folder or resource, and in any organization if necessary. In particular, the system administrator can modify permissions for
ROLE_ADMINISTRATOR, for example to share some resources across all organizations by making them read-only to
everyone, including the organization admins.
Organization admins are organization users with the ROLE_ADMINISTRATOR, such as the default jasperadmin created in
every organization. By default, organization admins have the Administer permissions to everything within their organization,
except what the system admin has changed to a lesser permission. However, organization admins cannot change the
permissions granted to ROLE_ADMINISTRATOR, to prevent them from overriding the settings of the system admin and
from locking themselves out of a folder or resource.

3.2.3.4 Default User Permissions

For all other 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 permissions that allow the sample users to access folders
and resources. We recommend you familiarize yourself with the permissions mechanism by viewing and setting permissions
in the sample data, as described in the following section.

3.2.4 Assigning 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 only set the permissions on that specific resource.

To set permissions on a folder or resource in the repository:

1. Log in as a user with administrative privileges.
2. Click View > Repository and locate the folder or resource.

36
 Repository Administration

3. Right-click the folder or the resource, and select Permissions... from the context menu .

The Assign Permissions by Role interface shows the existing role-based permissions in effect for the folder or resource. In
systems with multiple organizations, the roles displayed only include those in the scope of your user. In the default single
organization, the organization admin cannot see the permission for ROLE_SUPERUSER.
Permissions that are inherited are indicated by an asterisk (*).

Figure 3-3 Assign Permissions by Role Interface

4. For each role you want to grant access, select a value from the Permission Level drop-down.
Among the possible values, the permission of the parent folder is also indicated by an asterisk (*). Setting the permission
to the inherited value is the equivalent of removing an explicit permission.

There are two special cases:

Š You cannot explicitly set the permission level that in inherited from the parent folder, at least not directly. You
need to temporarily change the permission level on the parent folder, then set the explicit permission, and
finally set the parent folder’s permission back to the original value.
Š If none of the options in the drop-down are highlighted, the folder and its parent have been independently set to
the same value. To reset the permission level so that it once more inherits its parent folder, select a different
permissions level and click Apply; then select the permission with the asterisk and click Apply again.

5. Click Apply to save your changes before assigning permissions by user. If you are finished, click OK to save and return to
the repository view.
6. To assign permissions by user, click by User.
The Assign Permissions by User interface shows the existing user-based permissions in effect for the folder or resource.
In systems with multiple organizations, the users displayed only include those in the scope of your user. In the default
single organization, the organization admin cannot see the permission for superuser.
Permissions that are inherited are indicated by an asterisk (*).

37
JasperServer Administrator Guide

Figure 3-4 Assign Permissions by Role Interface

As shown in Figure 3-4, there are no user-based permissions defined by default. In this case, all access permissions have
been defined through roles.
7. For each user to you want to grant access, select a value from the Permission Level drop-down, as described in step 4.
8. Click Apply to save your changes and stay on an Assign Permissions page. If you are finished, click OK to save and return
to the repository.
9. Click Cancel to return to the repository without changing any permissions, for example, if you were only viewing the
current permission levels.

3.2.5 Testing User Permissions

Once you have configured users, roles, and permissions, Jaspersoft recommends that you test the permissions granted to a few
representative users. Testing is also recommended when you add new users, roles, and resources, and when you make any
major modifications to your access control configuration.

To test user permissions:

1. Log in as an administrator.
2. Select Manage > Users and locate the user whose access permissions you want to test.
3. 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
another user.
4. Select View > Repository, navigate to the desired folder, and verify that JasperServer displays the expected folders and
resources. Make a note of any objects that should be displayed but are not, and of any objects that should be hidden but are
displayed.
5. When you have verified this user’s permissions, click Log Out.
Your Home page appears.
6. Edit the permissions in the repository and modify the user or role definitions to correct the issues you noted in step 4.
7. Continue testing and updating JasperServer until the user’s permissions are correct.
8. Repeat these steps with several representative users to ensure that your access control is properly configured; an access
control configuration that hasn’t been tested doesn’t truly secure your data.

3.3 Multiple Organizations in the Repository

The architecture of the repository to support multiple organizations in a hierarchy requires certain considerations when
designing the repository structure for your deployment.
Within the repository, each organization has its own branch, contained in a folder named after the organization. JasperServer
automatically restricts users’ view and access to the branch of the repository in their organization’s folder. Organization
admins can create any folder structure needed within the organization.

38
 Repository Administration

Every level of the organization hierarchy, including the system or root level, has a folder named Organizations to contain sub-
organizations. The Organizations folder always contains a folder named Folder Template. When a new organization is created,
the entire contents of Folder Template is copied to a new folder under Organizations and given the name of the new
organization. The minimal folder structure required for new organizations includes a Topics folder under Ad Hoc Components
and a Temp folder. The admins can add any folders or resources to the Folder Template that will be used in subsequently
created organizations, for example data sources or a set of Ad Hoc Topics that can be modified to suit the needs of each sub-
organization.
The Public folder at the root is a special folder shared with all organizations. It is visible to every organization so that the
system admin can share certain resources in common, such as a data source, a company logo image, or a report template.

3.3.1 Design Considerations

Careful design of the JasperServer repository leads to a clear and robust environment for your BI environment and easy yet
secure access for users. One of the main decisions is how you want your organizations and users to access resources: which
resources are shared across organizations as opposed to which are specific to a particular organization. This usually breaks
down into several scenarios:
Š Organizations have private resources - Organizations have separate data sources, reports, analysis views etc. This would
be typical within an organization with departments. These private resources would be stored within each organization's
own folders, and perhaps only a few resources such as company logos would be shared between them.
Š Organizations share resources - Resources are kept in the public folders where they can be used by all organizations and
users. You may have common data sources and reports across customers, but the underlying data is partitioned by
organization. Data level security restricts what users see when running public reports and analysis views.
Š Organization share resources, but have some customizations - For example, users in the organization create reports that
are private and stored locally, but they access resources in the public folders.
Š Organizations have a hierarchical organization - You can have one organization containing other organizations. By
default, the parent organization can access all the resources of its child organizations. If you don't want this, you can avoid
creating sub-organizations or reprogram the JasperServer multi-organization filtering logic.

3.3.2 Referencing Resources in the Repository

All resources in the repository can be reference by Universal Resource Identifiers (URIs) giving the resource name and the
folder path where the resource are located. Because of the hierarchy of organizations, references are relative to the user
accessing them. JasperServer transforms relative references into actual resource locations in the repository based on the user’s
organization and the organization’s main folder. By default, folder locations are transformed in the following ways:
Š For organization members, locations in /public are not transformed, but those within the organization’s main folder seen
as / (forward slash) by the user are transformed to the actual location, for example /organizations/
organization_1.
Š For system admin, locations throughout the repository are not transformed. They see the actual repository path names.
This transformation allows some URIs to reference different resources depending on the organization of the user who accesses
them. For example, a report may have a public data source and an organization-specific logo as an image. We can set up the
report as follows:
Š Data source URI specified in the report unit: /public/CommonDataSource. Regardless of the user’s organization, this
always references the same repository resource.
Š Logo URI specified in the JRXML: /images/organizationLogo. When transformed for each user, the URI will access a
location relative to his organization’s main folder. The folder and image resource must have the same name in each
organization.
If any user in any organization runs this report, and has a logo image in their /images/organizationLogo resource, then the
report uses the public data source and displays their organization specific logo.
As shown in the example above, references found in JRXML resources are transformed before access. In the following cases,
references are not transformed in the user context and must work literally:
Š The reference to a data source, JRXML, and input controls within a report unit.
Š The reference to a data source and OLAP connections within an analysis view.

39
JasperServer Administrator Guide

Š The reference to a data source and schemas within an OLAP connection.

Because these references are not transformed at run-time, you must take the following measures:
Š The system admin cannot maintain these three types of resources in an organization level folder, because the organization
users would see errors when trying to access the referenced objects. The system admin must log in as a user of the
organization and do the maintenance in the context of the organization. For instructions, see 2.3, “Managing Users,” on
page 19.
Š These three types of resources cannot reference objects in the parent of an organization across organizations. For example,
if the data source for a report unit is set by a user in Org1 into /dataSources, a user in another organization can’t access
that data source because the reference is not transformed and the literal reference is in another organization.

3.3.3 Best Practices

The best practices for resources in a repository shared by multiple organizations are as follows:
Š The system admin must login as an organization user in order to maintain or run organization resources
Š Resources with absolute references to resources within organization folders only work for users within the organization or
within a parent organization
Š If a JRXML that accesses organization resources with URIs must run across organizations, then all organizations must
have identical folders, object names, and expected object types for those resources.
Š The public folder should be used for resources that are shared across organizations.

40
 Import/Export

4 IMPORT/EXPORT

The import and export utilities enable you to extract resources from, or add resources to, a JasperServer repository. The
utilities also handle users, roles, and organizations that JasperServer stores internally. Import and export can be helpful when
migrating between versions of JasperServer or when moving between test and production environments. The import and
export utilities are located in <js-install>/scripts.

This section assumes you are using Windows. If you are running JasperServer in Linux or Unix, the executable files
have the .sh file extension, which must be appended to the file name when you run the importer or exporter.

This chapter contains the following sections:

Š Importing Repository Resources
Š Exporting Repository Resources
Š Encrypting the Repository Database Password

4.1 Importing Repository Resources

Usage: js-import [OPTIONS]
Reads a repository catalog from the your file system and creates the named resource in the JasperServer repository. The
repository catalog must have been created with the js-export command, either as a ZIP archive file or a directory. The js-
import command has the following options:

--help Displays brief information about the available commands.

--input-dir Path for importing a catalog from a directory.

--input-zip Path and filename for importing a catalog from a zip file.

--update Resources in the catalog will replace those in the repository if their URIs and types match.

--skip-user-update When used with --update, users in the catalog will not be imported nor updated. Use this
option to import catalogs without overwriting currently defined users.

41
JasperServer Administrator Guide

--org-id When importing a 3.0 or 3.1 catalog for upgrade, specifies the ID of the organization in
which to place all catalog contents. If the organization does not exist, it is created as a top-
level organization. When not specified, 3.0 and 3.1 catalogs are imported into the default
Organization (organization_1). This option has no effect when importing a catalog from
version 3.5.

--org-label When importing a 3.0 or 3.1 catalog for upgrade and specifying an --org-id value that does
not yet exist, this option specifies the display name for the organization that are created.
When not specified, the display name is the same as the organization ID given. This
option has no effect when the organization ID already exists.

Examples:
Š Import the myDir catalog folder, prepending /importDir to all repository URIs:
js-import --input-dir myDir --prepend-path /importDir
For example, the folder /reports in the export catalog is imported to /importDir/reports.
Š Import the myExport.zip catalog archive file:
js-import --input-zip myExport.zip
Š Import the myDir catalog folder, replacing existing resources if their URIs and types match those found in the catalog:
js-import --input-dir myDir --update
Š Import a catalog made with a previous release into a new organization as part of an upgrade:
js-import --input-zip 31export.zip --org-id MyOrg --org-label UpgradedOrg
Š Import a a catalog made with a previous release into an existing organization as part of an upgrade:
js-import --input-zip 31export.zip --org-id MyOrg
The default behavior when a resource is found in the target repository that has the same URI as the resource that you are
attempting to import is to skip the creation operation and leave the existing resource unchanged (no overwrite occurs). To
delete the existing resource and replace it with a new one (of the same type and with the same URI), use the --update option.
Note that, if the resource in the export catalog is of a different type than the existing resource, JasperServer returns an error and
skips the update operation.

4.2 Exporting Repository Resources

Usage: js-export [OPTIONS]
Specifies repository resources such as reports, images, folders, and scheduled jobs to export to a folder structure on disk. You
can also export the internal definitions for users, roles, and organizations, as well existing audit data. The export output is
known as a repository catalog; it is either an archive file or a set of files in the file system. The js-export command has the
following options:

--everything Export everything except audit data: all repository resources, permissions, report
jobs, users, and roles.
This option is equivalent to: --uris / --repository-permissions
--report-jobs / --users --roles

--help Displays brief information about the available commands.

--output-dir Path of a directory in which to create the output catalog folder.

--output-zip Path and filename of the output catalog zip file to create.

--report-jobs Comma separated list of repository report unit and folder URIs for which report unit
jobs should be exported.
If a folder URI is specified, the folder is recursively traversed and JasperServer
exports the jobs defined for each report unit that is found.

42
 Import/Export

--repository-permissions When this option is present, repository permissions are exported along with each
exported folder and resource.
This option should only be used in conjunction with --uris.

--roles Comma separated list of roles to export; if no roles are specified with this option, all
roles are exported.

--role-users When this option is present, each role export triggers the export of all users
belonging to the role. This option should only be used in conjunction with --roles.

--uris Comma separated list of repository folder or resource URI paths

--users Comma separated list of users to export; if no users are specified with this options,
all users are exported. When specifying users, you must give their organization ID,
for example: --users superuser, "jasperadmin|organization_1", ...

--organizations Exports a catalog containing information about all organizations, but does not export
their users, roles, or resources. Information about each organization is given in a
separate file and includes its ID, display name, description, parent, and UID of the
organization’s main folder. You cannot specify individual organizations.

--audit Include audit data for all users, interfaces, and organizations in export.

Examples:
Š Export everything in the repository:
js-export --everything --output-dir myExport
Š Export the /reports/samples/AllAccounts report unit to a catalog folder:
js-export --uris /organizations/organization_1/reports/samples/AllAccounts --output-dir
myExport
Š Export the /images and /fonts folders:
js-export --uris /organizations/organization_1/images,/organizations/organization_1/
reports --output-dir myExport
Š Export all the resources (except users, roles, and job schedules) and their permissions to a zip catalog:
js-export --uris / --repository-permissions --output-zip myExport.zip
Š Export all the resources and all the report jobs:
js-export --uris / --report-jobs / --output-dir myExport
Š Export the report jobs of the /reports/samples/AllAccounts report unit:
js-export --report-jobs /organizations/organization_1/reports/samples/AllAccounts
--output-dir myExport
Š Export all the roles and users:
js-export --roles --users --output-dir myExport
Š Export the ROLE_USER and ROLE_ADMINISTRATOR roles along with all users belonging to either role:
js-export --roles ROLE_USER, ROLE_ADMINISTRATOR --role-users --output-dir myExport
Š Export two users:
js-export --users superuser, "jasperadmin|organization_1" --output-dir myExport
The --uris option allows you to specify one or more resource URIs. A URI can specify an resource such as a report. In this
case, all associated resources (such as images, subreports, data sources, resource bundles, and class files) are exported. A URI
can also specify a folder. If a folder is specified, the export operation exports all resources and folders contained in the folder.
In addition, it recurses through all its subfolders.
When you export a user, in addition to the user information, the user’s roles and properties are also exported. When you import
a user, if its roles exist in the repository, the user is given these roles. User properties are always imported.

43
JasperServer Administrator Guide

4.3 Encrypting the Repository Database Password

The repository is stored as a private database that only JasperServer may access. The import and export utilities also access
this database using the configuration settings in the file <js-install>/scripts/config/js.jdbc.properties. In this file, the
metadata.jdbc.password property displays the password to access the repository database in clear text. If the file
permissions on your system are not sufficient, you may want to encrypt this password for added security.

To encrypt the repository database password:

1. Run the js-encrypt-pass utility with the --pass password option and enter your password when prompted. For
example:

>js-encrypt-pass.bat --pass mypassword

Encrypting password: mypassword
Add next string to js.jdbc.properties:
metadata.jdbc.encryptedPassword=0x08,0x5a,0xf1,0x6d,0x96,0x13,0x3f,0x16,0xf2,0xd8

2. Open the file <js-install>/scripts/config/js.jdbc.properties for editing and replace the property
metadata.jdbc.password with the property and value that were output in step 1. In this example:

Replace:
metadata.jdbc.password=mypassword
With:
metadata.jdbc.encryptedPassword=0x08,0x5a,0xf1,0x6d,0x96,0x13,0x3f,0x16,0xf2,0xd8

44
 System Configuration

5 SYSTEM CONFIGURATION

You can edit text files to change the default behavior of JasperServer. This chapter describes a subset of the available
configuration options. Note that such changes only take effect after you restart JasperServer.
Configuration of the auditing feature is covered in section 6.2, “Configuring Auditing,” on page 64.
The file paths described in this chapter are all found under the <js-install> directory, which is the root of your JasperServer
installation. Because these file locations vary with your application server, the paths specified in this chapter are partial. For
example, the applicationContext.xml file is listed as residing in the WEB-INF folder; if you use Tomcat as your application
server, the default path to this location is:
C:\Program Files\jasperserver-pro-3.7\apache-tomcat\webapps\jasperserver-pro\WEB-INF.

Use caution when editing the files described in this chapter. Inadvertent changes may cause unexpected errors
throughout JasperServer that may be difficult to troubleshoot. Before changing these files, back them up.

Many configuration options are described in the JasperServer Installation Guide. Refer to this document for further
information.

This chapter includes:

Š Configuring Password Options
Š Changing the Login Page
Š Ad Hoc Configuration
Š Disabling the Domain Validation Check
Š Configuring JasperReports
Š Configuring the Heartbeat
Š Removing Report Scheduling Interval Options
Š Special Domain Support
Š Custom Data Sources
Š Configuring the Online Help
Š Configuring Search Behavior

45
JasperServer Administrator Guide

5.1 Configuring Password Options

5.1.1 Enabling Password Expiration

If your security policies require your users to change their passwords at regular intervals, you can enable password expiration.
In this case, JasperServer prompts users to change their passwords at the interval you specify. For example, if you set the
password expiry to 90 days, JasperServer prompts your users to change their passwords every three months. When a user’s
password expires, the user cannot log into JasperServer until she changes her password. The default value is 0; in this case,
passwords don’t expire.
If your users are externally-authenticated, do not enable the option.
When this option is enabled, JasperServer automatically enables the Change Password option on the Login page, even if
allowUserPasswordChange is set to false.

Password Administration Option

Configuration File
…\WEB-INF\jasperserver-servlet.xml (controls the Login page)
…\WEB-INF\applicationContext-security.xml (controls web services)

Property Value Description

passwordExpirationInDays TRUE Set the value to any positive, non-zero value to
<any other value> specify the number of days after which a
password expires.

5.1.2 Allowing Users to Change their Passwords

In order to change their passwords, users click the Change Password link that appears on the Login page. Enable this link
only if JasperServer authenticates your users. If your users are externally-authenticated, do not enable the option. To allow
users to change their passwords, you must edit a configuration file. Note that enabling the password expiration option
(described in the previous section) automatically enables the ability of end users to change their passwords.

Password Administration Option

Configuration File
…\WEB-INF\jasperserver-servlet.xml

Property Value Description

allowUserPasswordChange TRUE Set the value to TRUE to enable the
<any other value> Change Password link. Any other value
disables it.

46
 System Configuration

5.2 Changing the Login Page

By default, the JasperServer Login page provides links to various web resources. If you prefer the simpler Login page from
previous versions, specify it by editing a configuration file.

Login Page Administration Options

Configuration File
…\WEB-INF\jasperserver-servlet.xml

Property Bean Description

<prop key="/login.html" paramResolver Valid values for this property are login_welcome (the new
>login_mt</prop> default page), login (the default Login page from previous
releases), and login_oem (a generic login used by
Jaspersoft’s partners). For example, to revert to the
simpler Login page, set: <prop key="/login.html"
>login_mt_oem</prop>

You can change the look and feel of these pages by editing the corresponding JSP files in the \WEB-INF\jsp folder.

5.3 Ad Hoc Configuration

Ad Hoc options help you fine-tune the Ad Hoc Editor and the reports it creates. You must be logged in as a user with
ROLE_SUPERUSER to manage the Ad Hoc options and cache.

5.3.1 Ad Hoc Options

The Ad Hoc options determine how the Ad Hoc Editor creates and runs queries when designing and running reports. The
options that determine whether or not the Ad Hoc Editor optimizes queries are called data policies.

5.3.1.1 Configuring Ad Hoc Options

1. Log in as system administrator (superuser by default).
2. Select Manage > Ad Hoc Options.
3. In the Ad Hoc Filter List of Values Row Limit field, enter the maximum number of items that should be displayed in the
Condition Editor when a user defines filters for an Ad Hoc report based on a Domain. If this limit is exceeded when users
define filters, JasperServer displays a message to that effect.
Setting this to a lower value can improve performance.
4. In the Ad Hoc Dataset Row Limit field, enter the maximum number of rows that an Ad Hoc report can return.
JasperServer truncates the data when this limit is met.
Setting this to a lower number may improve performance, though your reports may not reflect the full data set.
5. In the Ad Hoc Query Timeout (seconds) field, enter the number of seconds JasperServer should wait before timing out
an Ad Hoc report while running its query.
Setting this to a lower number may prevent exceptions from being displayed to users who create and run Ad Hoc reports.
Setting this to a higher number may prevent complex calculations from timing out, but results in the use of more database
connections.
6. Check the box next to Optimize Queries for JDBC-based Reports if you want to create JDBC-based reports that are
processed in the database.

47
JasperServer Administrator Guide

7. Clear the check box next to Optimize Queries for Domain-based Reports if you want to create Domain reports that are
processed in memory.
The Optimize Queries for JDBC-based Reports and Optimize Queries for Domain-based Reports settings
do not retroactively update the existing reports in your repository. To change a report to use a different data
policy, change the appropriate setting, open the report in the Ad Hoc Editor, and save it.

8. Click Save to make your changes effective. Or click Reset to return to the previously saved values.

The Ad Hoc Options are not preserved after you restart the JasperServer instance. Every time after you restart
JasperServer, you must set the Ad Hoc Options to your preferred values again.

The following section gives more information about the data policies configured in the last two steps.

5.3.1.2 Understanding Data Policies

Data policies determine how JasperServer handles data loading and processing for certain kinds of Ad Hoc reports. They
determine how data is cached and where certain calculations occur. For example, you can specify that the data accessed by
Domain-based reports is grouped, sorted, and aggregated in the database rather than having JasperServer process it in memory.
By default, JasperServer relies on the database to group, sort, and aggregate data returned by queries based on Domains when
it is feasible. It also forces JasperServer to only retrieve the fields that appear in the report (rather than the entire set of fields in
the Domain). For queries based on JDBC data sources, such processing occurs in memory, and the entire result set defined in
the Topic is returned.
If a query contains only aggregate values, JasperServer can generally transform it into an aggregate database query, but some
functions (such as distinct count and average) must be calculated by reading all the detail rows from the database and
performing the aggregation in memory. Note that independent check boxes control the behavior: one for Domains and another
for JDBC data sources.
When these settings are disabled, JasperServer loads the entire set of fields associated with a Domain or Topic into memory,
and then applies the necessary grouping, sorting, and aggregation. This is also the case for Ad Hoc reports that do not rely on
Domains or JDBC data sources; in these cases, JasperServer processes the data in memory.
Generally, Jaspersoft recommends that these settings be enabled, especially when working with large data sets. In deciding
whether JasperServer should process the data in memory or push that processing to the database, consider these factors:
Š The size and complexity of your reports. Reports with complex sorting, grouping, or aggregation may perform better
when JasperServer optimizes the queries.
Š The amount of data in your data sources. If your data sources include a great deal of data, reports against them may
perform better when JasperServer optimizes the queries.
Š The number of users editing and running Ad Hoc reports. If you have a large number of users creating and running Ad
Hoc reports, performance may be better when JasperServer optimizes the queries. Implementations with fewer users may
perform better when the options are disabled.
Š The performance characteristics of your data source. If the database or other source of data is tuned for maximum
performance, Ad Hoc reports may perform better when JasperServer optimizes the queries. Note that, if your data source
is hosted by MySQL, Jaspersoft recommends that you clear the check from the Optimize Queries for Domain-based
Reports box.
Š The amount of memory allocated to JasperServer's Java Virtual Machine (JVM). If the JVM of the application server
hosting JasperServer is allocated plenty of memory, Ad Hoc reports may perform better when JasperServer optimizes the
queries. This is especially true if your data source tends to be slow.
To decide whether JasperServer should optimize queries for Ad Hoc reports, Jaspersoft recommends disabling these settings,
opening and saving some representative reports, and testing their performance. If the performance improves, leave the settings
disabled and re-save any similar reports.

5.3.2 Managing the Ad Hoc Cache

Ad Hoc reports use a cache to hold the data that it fetches. The cache improves the performance of data retrieval and sorting,
but it consumes memory. In order to minimize the amount of memory used by the cache, datasets are removed periodically; by

48
 System Configuration

default, datasets are removed if they have not been used for 20 minutes or if they have been in memory for 60 minutes. You
can change these defaults as described in 5.3.3, “Configuring Dataset Expiration,” on page 49.
The cache is used both when Ad Hoc reports are created and when they are run.

To view the Ad Hoc cache:

1. Click Manage > Ad Hoc Cache.
The Ad Hoc Dataset Caching page appears, displaying the cached datasets sorted by age.

Figure 5-1 Ad Hoc Cache Administration Page

2. To view the details of a dataset or remove it from the cache, click its name in the Query column.
The Dataset Caching Detail page appears, displaying the details of the query.

Figure 5-2 Ad Hoc Cache Entry Detail Page

3. To remove the dataset from the cache, click Clear from Cache.
4. To return to the Cache Administration page, click Back.

5.3.3 Configuring Dataset Expiration

In order to minimize the amount of memory used by the cache, datasets are removed periodically. You can change the

49
JasperServer Administrator Guide

frequency by editing a configuration file and specifying a different number of minutes.

Ad Hoc Cache Expiration

Configuration File
…\WEB-INF\applicationContext-adhoc.xml

Property Bean Description

defaultTimeoutMinutes dataSetCache The number of minutes to wait before removing a dataset
from the cache even when it is being used frequently. This
option ensures that stale data is periodically replaced with
fresh data from the data source. The default is 60 minutes.

defaultUnusedTimeoutMinutes dataSetCache The number of minutes to wait after a dataset is used

before removing it from the cache. The default is 20
minutes.

5.4 Disabling the Domain Validation Check

By default, JasperServer validates a Domain against its data source to ensure that the Domain design maps properly to the
underlying tables. This validation occurs when a Domain design file is uploaded to JasperServer. If your data source is very
large and complex, this validation can be time consuming. If the validation takes too long, you can disable it. In this case,
JasperServer assumes the Domain design is valid, and simply uploads it without the check. You can disable the validation by
editing a configuration file.

Login Page Administration Options

Configuration File
…\WEB-INF\applicationContext-semanticLayer.xml

Properties Bean Description

skipDomainDatabaseValidation slConfig By default, this property is set to FALSE; in this case,
JasperServer validates Domain designs against their data
sources. Set it to TRUE to disable this validation check.

If the tables and fields referenced in the Domain design don’t exist in the data source when this property is set to
TRUE, the Domain wizard won’t detect the problem, but the Choose Data wizard will return errors when your end user
work with the Domain.

5.5 Configuring JasperReports

JasperServer’s reporting features are built upon the JasperReports Library, which is embedded in JasperServer. Many of the
options you can configure to change JasperServer’s functionality are actually JasperReports options. JasperReports
configuration options can control many aspects of JasperServer behavior, from the way reports are exported into different file
formats, to the default font to use.
These options can be set at different levels of granularity: Global (applies to all reports generated by the server), Report
(defined in the JRXML and applies to a specific report), and Element (defined in the JRXML and applies to specific elements
of the report). Global properties are defined in the WEB-INF/classes/jasperreports.properties file.
For more information about JasperReports configuration, see http://jasperforge.org/website/jasperreportswebsite/trunk/
config.reference.html.

50
 System Configuration

The following sections highlight a few of the available options:

Š Extending JasperReports
Š Changing the Crosstab Limit
Š Setting a Global Chart Theme

5.5.1 Extending JasperReports

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

5.5.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 JasperServer 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. To do so, edit a
configuration file.

Crosstab Report Configuration Option

Configuration File
…\WEB-INF\classes\jasperreports.properties

Property Description
net.sf.jasperreports.crosstab. This value represents the maximum number of cells multiplied by the
bucket.measure.limit number of measures in the crosstab. 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.

5.5.3 Setting a Global Chart Theme

Chart themes control the look and feel of the charts generated by JasperServer. Chart themes can be applied at the level of
either the server or the individual report:
Š To apply a theme at the report level, select it when designing the report in iReport. Note that you can also apply a theme to
individual chart elements, as well. Note that a chart theme can be included in a report unit as a resource; in this case, the
theme is only available 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 a 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 this instance of JasperServer; they may
also be set as the global chart theme.

51
JasperServer Administrator Guide

To set a theme as the default chart theme, edit a configuration file.

Global Report Theme

Configuration File
…\WEB-INF\classes\jasperreports.properties

Property Description
net.sf.jasperreports.chart. The name of a chart theme that is in the WEB-INF\lib directory.
ChartTheme

Jaspersoft recommends that you create your chart themes in iReport; click File > New > Chart Theme. Then use iReport to
archive the new char theme as a JAR.

Chart themes do not apply to Ad Hoc chart reports.

5.6 Configuring the Heartbeat

During installation (or the first time an administrator logs in), you are prompted whether to participate in Jaspersoft’s
Heartbeat program, which reports specific information to Jaspersoft about your implementation, such as the operating system,
JVM, application server, RDBMS (type and version), and JasperServer edition and version number. Once this option is set,
you can change it by editing a configuration file.

Login Page Administration Options

Configuration File
…\WEB-INF\applicationContext-logging.xml

Property Bean Description

enabled heartbeatBean When this property is set to TRUE, JasperServer reports

information about your environment to Jaspersoft once a
week. When it is set to FALSE, information is not sent.

5.7 Removing Report Scheduling Interval Options

When users schedule reports they can specify that the report run periodically at regular intervals, When specifying simple
recurrence, JasperServer provides options down to the minute interval, which allows users to schedule the report to run every
minute.
Some administrators want to prevent users from scheduling reports too often; in this case, you can limit the options so that
users can only schedule the report down to the hour or day. To do so, edit an XML file.

Scheduling Options

Configuration File

reportJobBeans.xml

52
 System Configuration

Scheduling Options, continued

Section to Update Description

recurrenceIntervalUnits Comment out the intervals you want to restrict. To hide the Minutes
option in the interval drop-down list, comment out the
INTERVAL_MINUTE property.

For example, consider the case in which you want to hide the Minutes option in the interval field.
By default, the INTERVAL_MINUTE bean is:

<bean class="com.jaspersoft.jasperserver.war.dto.ByteEnum">
<property name="code">
<util:constant static-field="com.jaspersoft.jasperserver.api.engine.scheduling.
domain.ReportJobSimpleTrigger.INTERVAL_MINUTE"/>
</property>
<property name="labelMessage">
<value>job.interval.unit.minute.label</value>
</property>
</bean>

To comment it out, enclose the bean in comment characters:

<!--
<bean class="com.jaspersoft.jasperserver.war.dto.ByteEnum">
<property name="code">
<util:constant static-field="com.jaspersoft.jasperserver.api.engine.scheduling.
domain.ReportJobSimpleTrigger.INTERVAL_MINUTE"/>
</property>
<property name="labelMessage">
<value>job.interval.unit.minute.label</value>
</property>
</bean>
-->

You can also comment out the INTERVAL_HOUR bean if necessary.

5.8 Special Domain Support

When you use Domains with certain specific database constructs, you may need to configure JasperServer:
Š Enabling Oracle Synonyms
Š Enabling CLOB Fields
Š Enabling Proprietary Types

5.8.1 Enabling Oracle Synonyms

By default, Domains cannot access synonyms in an Oracle database. Set the following property to enable them. If you access
your Oracle database through JNDI, you also need to configure the JNDI connection.
Be aware that the Oracle metadata service works significantly slower when synonyms are in scope.

53
JasperServer Administrator Guide

Enabling Oracle Synonyms

Configuration File
…\WEB-INF\applicationContext-semanticLayer.xml

Properties Bean Description

includeSynonyms jdbcMetaConfiguration Set the value to true:

ForOracle <value>true</value>

Configuration File
...\META-INF\context.xml

Properties Bean Description

accessToUnderlying <Resource If you use JNDI, add the following property:

ConnectionAllowed name="jdbc/oracle"... accessToUnderlyingConnectionAllowed="true"

5.8.2 Enabling CLOB Fields

Support for CLOB (Character Large Object) fields is dependent on your database and must be enabled manually. If you want
to access CLOB fields in JasperServer, you must set the following options according to your database.
The Oracle JDBC driver implementation uses the CLOB JDBC type for CLOB fields.

CLOB Support for Oracle

Configuration File
…\WEB-INF\applicationContext-semanticLayer.xml

Properties Bean Description

jdbc2JavaType jdbcMetaConfiguration This property contains a map of database field types to Java
Mapping types. Find the line for CLOB that is commented out:
<!--entry key="CLOB" value=""/-->
Modify it as follows:
<entry key="CLOB" value="java.lang.String"/>

The MySQL JDBC driver implementation uses either the CLOB JDBC type, the LONGVARBINARY JDBC type, or both to
represent CLOB fields, depending on their length.

CLOB Support for MySQL

Configuration File
…\WEB-INF\applicationContext-semanticLayer.xml

Properties Bean Description

jdbc2JavaType jdbcMetaConfiguration This property contains a map of database field types to Java
Mapping types. Find the following lines:
<!--entry key="CLOB" value=""/-->
<!--entry key="LONGVARBINARY" value=""/-->
And modify them as follows:
<entry key="CLOB" value="java.lang.String"/>
<entry key="LONGVARBINARY"
value="java.lang.String"/>

54
 System Configuration

5.8.3 Enabling Proprietary Types

JasperServer provides a JDBC-to-Java type mapping for all standard JDBC column types for use in Domains. However, some
databases have proprietary types, such as NVARCHAR2 in Oracle. You can map these types with a special configuration.
As a prerequisite, the proprietary type must be logically equivalent to one of following Java classes:

java.lang.Boolean java.lang.Float java.lang.String java.sql.Timestamp

java.lang.Byte java.lang.Integer java.math.BigDecimal java.util.Date
java.lang.Character java.lang.Long java.sql.Date
java.lang.Double java.lang.Short java.sql.Time

There are two ways to create a mapping for a proprietary type, as shown in the following table
Š Modify the gerneric mapping for NUMERIC types. By default, any numeric type that doesn’t match one of the other types
is mapped to BigDecimal.
Š Create a secondary mapping under the special OTHER key, where the secondary key can be your custom type name.

Proprietary Database Type Mapping

Configuration File
…\WEB-INF\applicationContext-semanticLayer.xml

Properties Bean Description

jdbc2JavaType jdbcMeta Š To modify the generic mapping, edit this line:

Mapping Configuration <entry key="NUMERIC" value="java.math.BigDecimal"/>
Š Add any secondary key to the OTHER key, following this example:
<entry key="OTHER">
<map>
<entry key="NVARCHAR2" value="java.lang.String"/>
</map>
</entry>

5.9 Custom Data Sources

JasperServer provides built-in support for many commonly used data sources, such as JDBC, Java bean, and JNDI. However,
JasperServer does not include all JasperReports data sources, and you may have a custom JasperReports data source that you
want to use within JasperServer. In either case, you can extend JasperServer to support additional data sources by adding files
to your JasperServer configuration, as described in this section.

5.9.1 Data Sources in JasperServer and JasperReports

While a JasperReports data source is a different object than a JasperServer data source, they work together closely:
Š A JasperReports data source is an implementation of the JRDataSource interface that provides data organized in rows
and columns to the JasperReports filler; it produces a JasperPrint object. Each field declared in the JRXML corresponds to
a column in the JRDataSource output.
Š A JasperServer data source is a persistent object in the repository; it is typically created by stepping through a wizard. The
data source stores properties that tell JasperServer how to create a JRDataSource (typically in collaboration with a
JRQueryExecuter). These properties vary with the type of data source; for example, a JDBC data source needs a JDBC
driver, URL, user, and password. A data source can be defined as a public repository object that can be used by any report
unit (for example, the repository includes the /datasources/JserverJdbcDS if you installed the sample data), or as a local
object defined during the creation of a specific report unit.

55
JasperServer Administrator Guide

When JasperServer receives a request to run a report unit, it maps the report unit’s data source to an implementation of
ReportDataSourceService, which returns a JRDataSource based on the data source’s persistent properties. The
JRDataSource is used to fill the report and produce a JasperPrint object, from which JasperServer generates HTML or other
supported output formats.
Each JasperServer data source implementation must support the following features:
Š Read and write persistent properties in the JasperServer repository.
Š Provide a user interface for creating and editing instances that are integrated with the JasperServer web interface.
Š Create a JRDataSource using the property values for a specific data source instance, or pass parameters to a
JRQueryExecuter that produces the JRDataSource.
JasperServer’s built-in data sources rely on several Java classes, along with specialized Spring bean files, WebFlow
configurations, message files, and JSP files. The custom data source framework provides the same functionality by using a
Spring bean file, a message catalog, and a minimum of one Java file (more are required to support optional features).

5.9.2 JasperServer Data Sources and Query Executors

A query executer is an implementation of the JRQueryExecuter interface in JasperReports. It interprets the queryString
within the JRXML and produces a JRDataSource. JasperReports (either standalone or running within JasperServer)
determines which query executer to use by looking at the language attribute of the queryString and looking up a query
executer factory registered for that language.
JasperServer data sources can use two different methods to create a JRDataSource. The JasperServer data source can create
the a JRDataSource directly, without a queryString in the JRXML, or it can pass implementation-specific objects to the
query executer through the report parameter map. The query executer then uses the objects from the parameter map, as well as
the contents of the queryString, to create the JRDataSource.
The method to use depends on the nature of the data source, and whether you want to use a queryString to control your data
source. A good example of a data source using a query executer is the JDBC data source: it passes a JDBC connection to the
JDBC query executer, which it uses to pass the SQL queryString to the database.
The examples described in the following sections demonstrate both methods:
Š The custom bean data source creates a JRDataSource directly, which returns a hard-coded list of JavaBeans.
Š The webscraper data source can either create a JRDataSource directly, using the properties supplied by the data source
instance, or it can get those properties from a queryString in the JRXML. In this case, a data source instance isn’t
required. The sample reports for this data source each demonstrate one of these approaches.

5.9.3 Overview of the Example Custom Data Sources

Jaspersoft provides two example custom data sources:
Š Custom Bean Data Source
Š Webscraper Data Source
The examples are found in the <js-install>/samples/customDataSource directory of the computer hosting JasperServer. Once
you have deployed JasperServer to your application server, you can use Ant to build and deploy the examples.

5.9.3.1 Custom Bean Data Source

The custom bean data source implementation creates a data source from a collection of Java beans declared in the source code.
Its Spring bean definition file is in <js-install>/samples/customDataSource/webapp/WEB-INF/applicationContext-
sampleCDS.xml. Jaspersoft provides an example report that uses this data source; it is called simpleCDS.jrxml and is located
in the <js-install>/samples/customDataSource/reports directory.

5.9.3.2 Webscraper Custom Data Source

The webscraper custom data source implementation fetches a web page, decodes its HTML, and extracts selected data that is
turned into field values in the data source. Its Spring bean definition file is located in <js-install>/samples/
customDataSource/webapp/WEB-INF/applicationContext-webscraperDS.xml.
The example reports for this data source read a web page from http://www.craigslist.org and extract a list of items for sale.

56
 System Configuration

The webscraper data source configuration includes these elements:

Š URL: An HTTP URL that refers to the HTML page containing the desired content.
Š DOM path: An XPath expression that locates HTML elements to be turned into rows in the data source.
Š Field paths: XPath expressions for each field defined in the JRXML. JasperServer uses these paths to locate the field
value within each row selected by the DOM path.
The implementation creates a data source by:
Š Using the URL to issue a GET request for an HTML page.
Š Converting the HTML response into XML using JTidy (http://jtidy.sourceforge.net).
Using the DOM path to select XML elements from the converted response.
Creating a new data source row for each selected element.
Determining the context for each field based on its field path.
The data source takes two parameters: the URL of the web page and the XPath that determines how elements in the HTML
page become rows in the data source. The parameters can either be specified by a data source definition in the repository or by
a query string in the JRXML. JasperServer includes sample reports that each show one of these approaches:
Š The <js-install>/samples/reports/webscrapertest.jrxml report has no query. Instead, it relies on an instance of the custom
data source that you must create in the repository. Typical parameters to use with this data source are:
URL: http://sfbay.craigslist.org/search/car/eby?query=&neighborhood=62
DOM Path: /html/body/blockquote[2]/p
Š The <js-install>/samples/reports/webscraperQEtest.jrxml example contains a queryString element that specifies the
URL and the DOM path. It should be used without defining a data source instance, because JasperServer doesn’t run the
query executer for this particular implementation if a data source is defined for the report unit.

5.9.4 Prerequisites and Installation of the Example Custom Data Sources

5.9.4.1 About Apache Ant

If you used an installer to install JasperServer, you have Ant installed already. Run Ant using the following commands:
<js-install>/ant/bin/ant <ant-arguments>(Linux)
<js-install>\ant\bin\ant <ant-arguments>(Windows)
If you installed JasperServer manually with a WAR file, you must download Ant from http://ant.apache.org. Ant 1.6.2 was
used for testing, but earlier versions may also work.

5.9.4.2 About the Java Virtual Machine

Because you must recompile the Java source files, the JVM (Java Virtual Machine) used for installing the examples must be a
full Java Development Kit (JDK). Ensure that the JAVA_HOME environment variable points to a full JDK installation.

5.9.4.3 Installation
The sample directory includes:
Š build.xml: The Ant build file.
Š src: Java source directory.
Š webapp: A directory containing other files required by the examples, such as JSPs and Spring configuration files, which
are copied directly to the JasperServer web application directory.
Š reports: A directory containing example JRXML files that use the sample custom data sources.

To install the samples in your JasperServer web application:

1. At the command line, change directories to the custom data source sample directory (<js-install/samples/
customDataSource).
2. Edit build.xml and set the webAppDir property to the root of the JasperServer web application.

57
JasperServer Administrator Guide

3. Run the Ant command (as described in 5.9.4.1, “About Apache Ant,” on page 57) with no arguments; this executes the
default target, which is named deploy. The deploy target initiates these actions:
Š Compiles the Java source under the src directory.
Š Deploys the compiled Java class files to the JasperServer web application.
Š Deploys files under the
Š webapp directory to the JasperServer web application.
4. Restart the application server.

These steps only make the example custom data sources themselves available in JasperServer. To test the data
sources, you must also create instances of the custom data sources in JasperServer, then upload the reports that
accompany the samples.

5.9.5 Creating a Custom Data Source

A custom data source consists of Java code, a message catalog, and a Spring bean definition file that configures all the parts of
the implementation with JasperServer. This section describes the implementation of a custom data source.

5.9.5.1 Files Used by a Custom Data Source Implementation

Types of files Path (relative to web application Description

directory)
Spring bean WEB-INF/applicationContext-<name>.xml Defines Spring beans needed to configure the
definition where <name> uniquely identifies your custom data source. Choose a unique name starting
data source with applicationContext- and ending with .xml
Message catalog WEB-INF/bundles/<cat_name>.properties Defines messages used by the data source
where <cat_name> uniquely identifies your custom implementation (this path is referenced in the
data source Spring bean definition file).
Implementation WEB-INF/lib or WEB-INF/classes Any Java code required by the implementation.
classes

5.9.5.2 Implementing the ReportDataSourceService Interface

A custom data source requires an implementation of the ReportDataSourceService interface, which sets up and tears
down data source connections in JasperServer. It relies on:
Š void setReportParameterValues(Map parameterValues): called before running a report; it creates resources
needed by JasperReports to obtain a JRDataSource, and adds them to the parameter map.
Š void closeConnection(): cleans up any resources allocated in setReportParameterValues().

5.9.5.3 Defining Custom Data Source Properties

A custom data source can define properties that help users configure each data source instance differently, in the same way
that a JDBC data source has properties for JDBC driver class, URL, user name, and password. While implementing your
ReportDataSourceService, Jaspersoft recommends that you consider which properties you’ll need.
For more information on properties definition, refer to 5.9.5.3, “Defining Custom Data Source Properties,” on page 58).
There are two kinds of properties:
Editable properties that must be string values. When you use the JasperServer data source wizard to create an instance of your
custom data source, you can enter values for the editable properties using text fields. These values are persisted when you save
the data source.
Hidden properties that can be of any type. These property’s values are determined by the Spring configuration file: they are not
persisted, nor are they visible in the data source wizard. Use them to give your
ReportDataSourceService implementation access to a Spring bean instance. For an example of a hidden property, refer to
the repository property in the custom bean data source definition in the XML example in 5.9.5.6, “Defining the Custom
Data Source in Spring,” on page 60.

58
 System Configuration

These property values are set by the custom data source framework after it instantiates your ReportDataSourceService
implementation. You need property setters and getters corresponding to each property name; for example, if you defined a
property with the name foo you need getFoo() and setFoo() methods.

5.9.5.4 Implementing Optional Interfaces

If you want to use the value of the queryString in the JRXML to obtain your data source, you must create implementations
of the JRQueryExecuter and JRQueryExecuterFactory interfaces.
JRQueryExecuterFactory has this method:
JRQueryExecuter createQueryExecuter(JRDataset dataset, Map parameters): returns a
JRQueryExecuter for the given dataset and parameter map.
JRQueryExecuter has these methods:
JRDataSource createDatasource(): returns the actual data source based on the parameter map passed to the
JRQueryExecuterFactory; most likely, you will create a JRDataSource implementation suitable for your data
source.
close(): called when the report filling process is done with the data source.
cancelQuery(): called to clean up resources if the report filling process is interrupted.
If you want to provide validation in the data source creation wizard in JasperServer, you must create an implementation of
CustomDataSourceValidator. It has the following method:
validatePropertyValues(CustomReportDataSource ds, Errors errors): checks parameters and call
errors.rejectValue() with the appropriate property name and error code (defined in a message catalog; for more
information, refer to 5.9.5.5, “Creating the Message Catalog,” on page 59).

5.9.5.5 Creating the Message Catalog

The message catalog contains messages displayed by JasperServer’s data source wizard when creating and editing custom data
source instances. The various types of messages are shown in the following table, along with message naming conventions:

Message Type Naming Convention

Name of the custom data source type Cdsname.name (where cdsname is the value of the name property of the custom
data source).
Name of the custom data source Cdsname.properties.propname (where propname is the name of the
property property that the user must define when creating a custom data source).
Validation messages Cdsname.any.message.code (JasperServer does not enforce a convention,
but Jaspersoft recommends starting with cdsname for consistency).

For example, the webscraper message catalog contains the following:

webScraperDataSource.name=Web Scraper Data Source

webScraperDataSource.properties.url=URL
webScraperDataSource.properties.path=DOM Path
webScraperDataSource.url.required=A value is required for the URL
webScraperDataSource.path.required=A value is required for the DOM path

59
JasperServer Administrator Guide

5.9.5.6 Defining the Custom Data Source in Spring

To configure your data source, you must add an instance of CustomDataSourceDefinition to the Spring bean definition
file. This class has the following properties:

Name Required Value

factory Yes A fixed value of ref="customDataSourceFactory"
This bean manages all the custom data sources.
name Yes A unique name that identifies this data source to the custom data source
framework. It is also used as a prefix for all messages in the message catalog.
Choose the name that is not used by other custom data sources.
serviceClassName Yes A class name for your ReportDataSourceService implementation.
validator — An instance of your CustomDataSourceValidator implementation.
propertyDefinitions — Information describing each property used by the data source implementation,
structured as a list of maps.
queryExecuterMap — Map with query languages (uses the language attribute of JRXML
queryString element) as keys and JRQueryExecuterFactory class
names as values.

The propertyDefinitions property is a list of maps, each one describing a property of the custom data source
implementation. It includes these entry keys:

Name Required Value

name Yes Name of property that matches a Java Bean property in the
ReportDataSourceService implementation; it is also used in message catalog keys.

default — A default value for the property.

hidden — If a property has the hidden entry key set to true, then its value is fixed to that of the
default entry key. Such properties are not be editable in the JasperServer data source
wizard, nor are they persisted. This is handy for making Spring beans accessible to
ReportDataSourceService implementations.

The following XML defines a CustomDataSourceDefinition bean for the custom bean data source example:

<bean id="myCustomDataSource"
class="com.jaspersoft.jasperserver.api.engine.jasperreports.util.CustomDataSourceDefini
tion">
<property name="factory" ref="customDataSourceServiceFactory"/>
<property name="name" value="myCustomDataSource"/>
<property name="serviceClassName"
value="example.cds.CustomSimplifiedDataSourceService"/>
<property name="validator">
<bean class="example.cds.CustomTestValidator"/>
</property>

60
 System Configuration

<property name="propertyDefinitions">
<list>
<map>
<entry key="name" value="foo"/>
</map>
<map>
<entry key="name" value="bar"/>
<entry key="default" value="b"/>
</map>
<map>
<entry key="name" value="repository"/>
<entry key="hidden" value="true"/>
<entry key="default" value-ref="repositoryService"/>
</map>
</list>
</property>
</bean>

5.9.5.7 Configuring the Message Catalog

To configure your message catalog with JasperServer, add a bean definition similar to the following to the Spring definition
file that you created in “5.9.5.6, “Defining the Custom Data Source in Spring,” on page 60”:

<bean class="com.jaspersoft.jasperserver.api.common.util.spring.GenericBeanUpdater">
<property name="definition" ref="addMessageCatalog"/>
<property name="value" value="WEB-INF/bundles/cdstest"/>
</bean>

For the value property, substitute the location of your message catalog file, omitting the .properties extension. Setting the
addMessageCatalog property precludes the need to edit the messageSource bean definition in applicationContext.xml. Note
that, if you also supply localized versions of the message catalog that follow the Java resource bundle naming convention,
users with other locales automatically see the localized strings when creating a new data source of this type.

5.9.6 Installing a Custom Data Source

To install your custom data source in JasperServer, add all the files it requires to the JasperServer web application directory.
For the correct locations, refer to the table in 5.9.5.1, “Files Used by a Custom Data Source Implementation,” on page 58.
After adding the files, restart JasperServer.
When you create a new data source in JasperServer, the new custom data source type appears in the list of available data
source types. If the new type is selected, JasperServer displays a form containing the list of properties you configured.
When the form is submitted, the parameter values are validated with your CustomDataSourceValidator implementation
and appropriate validation messages are displayed. Once the data source is validated, save it to the repository. The data source
can now be used in a report or analysis connection.

5.9.7 Using a Custom Data Source in Reports

When defining <queryString> in JRXML, use a language setting that your custom data source supports.
When you add a report to the repository, you can either define a local data source, or you can select one of the data sources in
the repository. In either case, you can use an data source based on your custom data source implementation. In the case of a
data source in the repository, you must create it before adding the report. If, during the creation of your data source, the custom

61
JasperServer Administrator Guide

data source is not listed as an available data source type, the custom data source is not properly installed. For details, refer to
5.9.6, “Installing a Custom Data Source,” on page 61.

5.10 Configuring the Online Help

JasperServer includes an online help system that describes the web interface. If your users don’t have internet connectivity, or
if you don’t want to provide access to this system, you can configure JasperServer to hide the help links completely.

Online Help Configuration Options

Configuration File
…\WEB-INF\applicationContext-webHelp.xml

Property Bean Description

showHelp webHelp Determines whether the help links are displayed in the JasperServer web
UI. Valid values are true and false.
The help link appears on the login page (Online Help) as well as to the left
of Logout on other JasperServer pages.

hostURL webHelp Indicates the name of the computer hosting the web server where the help
is running. The value depends on the version of JasperServer. Do not
change this value.

pagePrefix webHelp Defines the default page name to pass to the web server hosting the help
system. The only valid value is Default_CSH.htm for this property.

helpContextMap webHelp Maps contexts in the application to topic identifiers in the help system.
Many pages in the JasperServer web application are configured for
context-sensitivity. When a user clicks Help on such a page, JasperServer
loads a specific topic in the help system. The topic that appears is
determined by a map in the applicationContext-webHelp.xml file. The only
valid values are the defaults.

5.11 Configuring Search Behavior

By default, JasperServer allows users to search the entire repository to find any resource for which they have read permission.
If you prefer to limit access to the repository based on the old browsing model, where users can only access folders for which
they have read permission, you can disable the ability to search subfolders.

Online Help Configuration Options

Configuration File
…\WEB-INF\applicationContext-search.xml

Property Bean Description

modes searchConfiguration To disable subfolder search, remove or comment out the line:
<util:constant static-field="..SearchMode.SEARCH"/>
Users no longer see the check box to Include subfolders on the
repository search page. When subfolder search is disabled, the
search field at the top of all pages no longer behaves like a global
search. This setting applies to all users, including administrators.

62
 Auditing

6 AUDITING

Auditing records key events that are of interest to system administrators, such as login/logout, user, report generated, report
details such as parameters selected and generation time, and object sizes. The events can be saved and archived. The archiving
can be set to move saved events to the archive after a specific number of days.
This chapter contains the following sections:
Š Audit Events
Š Configuring Auditing
Š Using the Audit Domains
Š Importing and Exporting Audit Data

6.1 Audit Events

In broad terms, an audit event is any atomic operation that can be monitored by the audit system. Event properties and
attributes are features of the event; they can be defined internally or in custom code.
The following table lists the defined audit events and the information that is collected about them. For every recorded event,
JasperServer logs the time it occurred and the user who initiated it. See the configuration file applicationContext-audit.xml for
complete specification of the events.

Event Information Collected

Log in or log out Time and user ID (recorded for every event)

Log in as User logged in as

Run report (from repository or Š Report referenced

from Ad Hoc Editor) or run a Š Data source referenced
subreport within any other report
Š Report parameters and values
Š Report queries (SQL, Domain, HQL, generated SQL, etc.)
Š Execution start, end
Š Query execution time
Š Report rendering time
Š Caching parameters
Š Errors that occurred

63
JasperServer Administrator Guide

Event Information Collected

Report schedule created, Š Report referenced
deleted, or updated Š Scheduling parameters and values

Scheduled report run Š Report output

Š Report delivery parameters (emails, etc.)
Š Same parameters as when report is run in Ad Hoc

Creating report in Ad Hoc Editor Š Field added as a column

Š Field added as a group

Resource accessed for any Š Resource referenced

reason (view, used in report, Š Resource type
etc.)

Resource added or updated Š Resource referenced

Š Resource type

Resource or folder deleted Resource or folder referenced

Permissions added, updated, or Š Resource or folder referenced

deleted Š Previous permissions (before update)

User added, updated, or deleted, Š User ID

also user password change Š User name
Š Email
Š Enabled flag
Š External flag
Š Profile attributes

Role added, updated, or deleted Š Role ID

Š Role name
Š Role organization

Organization added, updated, or Š Organization ID

deleted Š Organization description

6.2 Configuring Auditing

Configuration settings for audit logging are in the configuration file applicationContext-audit.xml.

6.2.1 Enabling Auditing

By default, auditing is off.
To enable auditing, in the configuration file set:
<entry key="com.jaspersoft.jasperserver.api.logging.audit.domain.AuditEvent" value="true"/>.
To disable auditing, set value="false".

6.2.2 Archive Options

Archiving is on when auditing is on. However, you should set the archiving interval to a level appropriate for your
organization. Use the bean auditServiceTarget.

64
 Auditing

Auditing Archive Options

Configuration File
…\WEB-INF\applicationContext-audit.xml

Property Bean Description

maxAuditEventAge auditServiceTarget The number of days to keep audit data in the active database.
ToArchive Older data is moved to the archive.

maxAuditEventAge auditServiceTarget The number of days to keep the data. Older data is purged
(deleted). Zero, the default, means old data is never purged.

cronExpression auditEventArchiverTrigger Defines the frequency of the archiving job in cron syntax.

cronExpression auditEventPurgerTrigger Defines the frequency of the audit purge job in cron syntax.

The cronExpression properties use standard cron syntax. For example, 0 0 3 * * ? runs a job once a day at 3 a.m.

6.2.3 Events and Properties

By default, all events and properties are logged. To enable or disable logging of a given event or property, use the
configuration file.
In the file, event types and their properties are listed in the enabledEventsMapping map (<util:map
id="enabledEventsMapping">). The map has three parts:
Š WEB_SERVICES – Event types related to accessing JasperServer through a web service.
Š GUI – Event types for access through a user interface.
Š INTERNAL – Event types used by JasperServer itself, such as when running a scheduled report.
To disable an event, comment it out. For example:
<!-- <entry key="createFolder" value="folderName,folderLabel,folderDescription,exception"
/> -->
To disable a property, use any of these measures:
Š Delete the property. For example, remove folderDescription, resulting in:
<entry key="createFolder" value="folderName,folderLabel,exception" />
Š Disable it with the | syntax. For example:
<entry key="createFolder" value="folderName,folderLabel,|folderDescription,exception" />
Š Use the “all except” *| syntax to specify only the disabled property. All others will be recorded. For example:
<entry key="createFolder" value="*|folderDescription" />

6.3 Using the Audit Domains

You can use the Ad Hoc Editor to explore the audit data and generate reports. Two domains were created for this purpose:
Š Audit Domain – Use this Domain to run reports on current audit data; they run against the active audit database.
Š Audit Archive Domain – Use this Domain to run reports on archived data; they run against the archive database.
The contents of both Domains are identical, the only difference is the database that is accessed in each case.
In Ad Hoc, the Domains are on the Domains tab. In the repository, the Domains are in the Public/Audit folder. In both cases,
the audit Domains are visible and accessible only to administrators.
For instructions on using Domains in reports, see the Ad Hoc chapter in JasperServer User Guide. For documentation of
Domains in general, see the Domains chapter in the same manual. The next section documents the contents of both Domains.

65
JasperServer Administrator Guide

6.3.1 Domain Items

The following tables describe the items in both Domains, which correspond to the information that is recorded for each event.
When creating a report based on either Domain, choose the items that correspond to the type of event you want to report on.
Domain items in the following table are used in general events and repository events:

Domain Item Explanation

Date Date event occurred.

Prop Long Value clob value of event property, such as query.

Prop Type Type of event property, such as destination folder, as per event map in
configuration file.

Prop Value string value of event property, such as folder name.

Time Time event occurred.

Event Type Type of event, such as save resource, as per event map in configuration file.

Request Type Repository request type of event.

Resource Type Repository type of resource accessed in event.

Resource URI URI of repository resource.

Domain items in the following table are recorded for user events:

Domain Item Explanation

E-mail E-mail address of event user (user at time of event).

Enabled Whether event user is currently a user.

External Whether event user was an external user.

Full Name Full name of event user.

Password Changed Whether event was a change of password

Organization Organization of event user.

User Name UserID of event user.

Domain items in the following table are recorded for role events:

Domain Item Explanation

External Whether role was defined in an external system.

Role Name Name of the role in the event.

Organization Organization of the role in the event.

Domain items in the following table are recorded when a report is generated:

Domain Item Explanation

Date Date the report is generated.

Time Time the report is generated.

Resource URI URI of repository resource accessed for report.

66
 Auditing

Domain Item Explanation

Resource Type Repository type of resource accessed for report.

Datasource URI URI of data source accessed for report.

Query Execution Time Time to execute the query in the database.

Report Rendering Time Time to prepare query results for display.

Report Execution Time Total time to execute the report (query execution + report rendering).

Query Specification of the report query.

User Name UserID of event user.

Organization Organization of event user.

Crosstab Group Field Field name used in crosstab

6.3.2 Sample Reports

A number of sample Ad Hoc reports based on the audit Domains are provided in the Public/Audit/Audit Reports repository
folder. As with all audit material, these reports are visible only to administrators. The reports provide an example of the data
that is recorded and how it can be used for auditing. You can also modify these reports in the Ad Hoc Editor to suit your
auditing requirements:
Š Audit Report – Generic example of a an audit report showing commonly audited events.
Š Performance Crosstab Report – A crosstab that shows average performance of reports that were run.
Š Performance Report – Generates a list of reports that were run and sorted by run-time to identify slow reports.
Š Repository Resources Report – Shows repository resources and their associated events.
Š Resource Execution Report – Generates a list of reports that were run.
Š User Activity Report – Generates a list of reports run by a specific user.

The parameters for these reports and the report contents are blank by default, because auditing is disabled by default
and no audit data exists. To view these reports, first enable auditing as described in section 6.2, “Configuring
Auditing,” on page 64, then wait for user activity to generate events.

The same reports are also provided in the Public/Audit/Audit Reports/Archived Audit Reports folder. These reports are
identical to those listed above, except they use the Audit Archive Domain and run against the archived audit data. These
reports are blank until you enable auditing and archiving and until audit data is archived by the audit archive configuration.

6.4 Importing and Exporting Audit Data

Audit data can be imported and exported using the import and export utilities described in chapter 4, “Import/Export,” on
page 41.
Š To import audit data, import the folder that contains it.
Š To export audit data, use the --audit option in the export command.

67
JasperServer Administrator Guide

68
 Integrating JasperServer and Talend Integration Suite

7 INTEGRATING JASPERSERVER AND TALEND INTEGRATION SUITE

Talend Integration Suite Enterprise Edition (TIS EE) is a complete and ready-to-run data integration platform that provides
high performance data extract-transform-load (ETL) capabilities. TIS EE is well suited for all analytic and operational data
integration needs, both simple and complex. When used in conjunction with JasperServer, TIS EE can help you develop,
manage, and document data integration processes for more accurate and comprehensive reporting and analytic processing.
If you use both JasperServer and TIS EE, you can integrate them such that your administrators access TIS EE from within
JasperServer without having to login to TIS EE explicitly. In this case, JasperServer displays a new menu item (Manage >
ETL) to users who are identified as TIS EE administrators. When a user clicks this menu item, JasperServer launches the TIS
EE Admin page in a new browser window.
This section describes the configuration this feature. For more information about TIS EE, refer to the documentation that
accompanies it.

JasperServer can also be used in conjunction with JasperETL (instead of TIS EE). However, since JasperETL does
not include a repository, there isn’t a direct integration option.
For more information on JasperETL, refer to its documentation.

Integration between JasperServer and TIS EE depends on these factors:

Š TIS EE and JasperServer must be deployed in the same application server.
Š Each user who will have access to TIS EE through JasperServer must exist in both applications and have identical names.
In order for this feature to function properly, TIS EE and JasperServer must be deployed in the same application server. At a
high level, configuration revolves around identifying ETL administrators and includes creating users, assigning permissions,
and testing the integration.

7.1 Configuring ETL Administrators

Each user that will access TIS EE through JasperServer must be configured as an ETL administrator: the user must exist in
both applications, and each user’s name must match in both systems.
For more information, refer to the TIS EE documentation.

To configure an ETL administrator:

1. In JasperServer, create a user who will administer TIS EE.
For information, see 2.3, “Managing Users,” on page 19.

69
JasperServer Administrator Guide

Because TIS EE requires each user name to be a valid email address, the user name of an ETL administrator in
JasperServer must also be a valid email address. For example, if [email protected] is a TIS EE user, you must create
a user named [email protected] in JasperServer.
2. Assign the user the ROLE_ETL_ADMIN role, as well as well as any other roles this user needs.
For more information about roles in JasperServer, see 2.4, “Managing Roles,” on page 22.
3. Log in to the TIS EE administration application and create a user with the same name as the user created in step 1.
4. Assign this user the appropriate role.

Your users’ passwords are not synchronized between the two applications. However, since the password isn’t
explicitly checked when the user clicks Manage > ETL, password changes in either system do not have any ill effect
on JasperServer’s integration with TIS EE.

7.2 Testing Integration with TIS EE

To test the integration:
1. Click Manage > Users, and locate and click a user you have configured as an ETL administrator.
The User page appears.
2. In the upper left-hand corner of the page, click Log in as User.
The selected user’s Home page appears.
3. Click Manage > ETL.
The user’s TIS EE Home page appears in a new window. If the Manage > ETL option does not appear, this user does not
have the ROLE_ETL_ADMIN role.
4. If the TIS EE home page does not appear, you may need to verify your system and user configuration:
Š Verify that the applications are deployed to the same application server.
Š Verify that the user exists in both applications and has the same name in each.
Š Verify that the user has the ROLE_ETL_ADMIN role in JasperServer.
5. When you are done testing, logout of TIS EE, and click Log Out in JasperServer to return to your Home page.

70
 Integrating JasperServer and Liferay Portal

8 INTEGRATING JASPERSERVER AND LIFERAY PORTAL

These instructions assume that both JasperServer and Liferay have been installed properly. For instructions about installing
Liferay, refer to its documentation. For instructions about installing JasperServer, refer to the JasperServer Installation Guide.
This chapter also assumes:
Š You are using Liferay deployed in Tomcat.
Š <js-install> is the root of your JasperServer installation.
Š <liferay-install> is the root of your Liferay installation. This path cannot contain any spaces.
Š <liferay-install>\<tomcat-dir> is the root of the Tomcat instance running Liferay.

These instructions describe how to deploy the portlet WAR that is included in the JasperServer distribution. If you are
implementing the JasperServer portlet from a different distribution, refer to the instructions provided in that
distribution.
If you are upgrading from a previous version of JasperServer in which you deployed the Liferay portal, you must take
additional steps; pay careful attention when following the instructions in this chapter.

You can get Liferay from http://www.liferay.com.

8.1 Changing Liferay’s Port Numbers

By default, both Liferay and JasperServer run on port 8080. You must change Liferay’s listening port to avoid this conflict.
For example, you can change Liferay’s listening port to 7080. You must also update a number of other Liferay ports.

To configure Liferay’s port numbers:

1. In the server.xml file (found at <liferay-install>\<tomcat-dir>\conf\), change all the occurrences of port numbers. For
example:

Port Default Suggested

Server Port 8005 7005

Non-SSL Connector Port 8080 7080

AGP 1.3 Connector Port 8009 7009

Proxy Connector Port 8082 7082

71
JasperServer Administrator Guide

2. In the server-minimal.xml file (found at <liferay-install>\<tomcat-dir>\conf\), change all the occurrences of port numbers.
For example:

Port Default Value Suggested Value

Server Port 8005 7005

Catalina Connector Port 8080 7080

AGP 1.3 Connector Port 8009 7009

3. Start the Liferay Portal by entering the following at the command prompt:

Linux <liferay-install>/<tomcat-dir>/bin/startup.sh
Windows <liferay-install>\<tomcat-dir>\bin\startup.bat

8.2 Configuring JasperServer to Accept Web Services Calls

Configure JasperServer to accept web service calls from Liferay by updating:
<js-install>/webapps/jasperserver-pro/WEB-INF/applicationContext-security.xml.

To configure JasperServer to accept web services from trusted hosts:

1. Start JasperServer.
2. Locate the trustedIpAddress property in the applicationContext-security.xmli file found at <js-install>/webapps/
jasperserver-pro/WEB-INF.
3. Add the IP address of your Liferay Portal host. For example, if Liferay is running on a computer with the IP address
123.45.6.789, the trustedIpAddress property would be:

<property name="trustedIpAddress">
<list>
<value>123.45.6.789</value>
</list>
</property>

You can also use the value localhost or 127.0.0.1 for this property.
4. Restart JasperServer.

8.3 Configuring Liferay to Access JasperServer

The JasperServer portlet uses web services to retrieve information from JasperServer. This parameter specifies the
JasperServer repository web service URL. It’s normally of the form:
http://<host:port>/jasperserver-pro/services/repository
or
https://<host:port>/jasperserver-pro/services/repository
For example:
http://123.45.6.789:7080/jasperserver-pro/services/repository

72
 Integrating JasperServer and Liferay Portal

To configure Liferay to access JasperServer:

1. Locate the jasperserver_repository_ws_url parameter of the portlet.xml file found at <liferay-install>/<tomcat-
dir>/webapps/<JasperServerPortlet-x.x.x>/WEB-INF.
2. Set its value to the URL of the JasperServer repository web service. For example:

<init-param>
<name>jasperserver_repository_ws_url</name>
<value>http://123.45.6.789:8080/jasperserver-pro/services/repository</value>
</init-param>

3. Restart Liferay.

8.4 Testing Liferay

To test Liferay:
1. Enter your Liferay Portal URL in your browser’s address bar. For example:
http://<liferay host>
2. Login to Liferay; by default the sample data in Liferay includes a default Admin user with these credentials:
Š User name: [email protected]
Š Password: bruno
3. If the sample data is used, the default administrative user becomes valid:
Š User name: [email protected]
Š Password: test
If the portal appears, Liferay is properly installed.

8.5 Deploying the JasperServer Portlet WAR File

If you are upgrading from a previous version of JasperServer in which you deployed the portlet WAR file, you must delete the
webapps/Jaspersoft folder of the application server hosting Liferay. This deletes libraries used in older versions that conflict
with libraries in the latest version. Once this folder is deleted, you can deploy the new portlet WAR.

To deploy the portlet WAR file,

1. Copy JasperServerPortlet-3.7.0.war to <liferay-install>\<tomcat-dir>\deploy
2. Ensure that Liferay is running.
3. Login on the Liferay Portal as a user with administrative privileges. For example, [email protected]. The default
password is bruno.
If you just started Liferay, it attempts to deploy the WAR file (this step may take several moments, depending on your
environment).
4. When Liferay finishes the deployment, click Add Application > Jaspersoft > JasperServer Portlet appears.
If the JasperServer portlet appears, it is deployed.
Note that you can run multiple instances of the portlet at once.

73
JasperServer Administrator Guide

8.6 Configuring a Default Report to Display

By default, the portlet displays all the reports that the current user is allowed to view. You can configure the portlet to display
a specific report, instead.
In the portlet.xml file, add the following entries to specify a default report:
Š full_resource_path: This parameter specifies the full report Path.
Š resource_type: The only supported value is report
Š number_of_parameters: This specifies the number of parameters the report requires, including optional and required
parameters.
Š js_resource_parameter_<parameter>: For each parameter of the report, append prefix
js_resource_parameter_ to the name. In this example, the report /reports/samples/EmployeeAccounts takes a
parameter named EmployeeID; it is defined as js_resource_parameter_EmployeeID.
Š modifiable: This value has to be 1 [one] so end users can choose different reports at run time. 1 is the only supported
value. For details of this parameter, please refer to the JSR-168 specification.
For example, the portlet configuration section of the portlet.xml file might be similar to the following:

<portlet-preferences>
<preference>
<name>full_resource_path</name>
<value>/reports/samples/EmployeeAccounts</value>
<modifiable>1</modifiable>
</preference>

<preference>
<name>resource_type</name>
<value>report</value>
<modifiable>1</modifiable>
</preference>

<preference>
<name>number_of_parameters</name>
<value>1</value>
<modifiable>1</modifiable>
</preference>

<preference>
<name>js_resource_parameter_EmployeeID</name>
<value>beth_id</value>
<modifiable>1</modifiable>
</preference>
<portlet-preferences>

If you remove this section, the JasperServer Portlet displays a list of reports that the current user can access.

8.7 Testing the JasperServer Portlet

To test the portlet:
1. Login to Liferay as described in 8.4, “Testing Liferay,” on page 73.
2. Verify that the reports you configured in 8.6, “Configuring a Default Report to Display,” on page 74 appear in the
JasperServer portlet.

74
 Integrating JasperServer and Liferay Portal

3. If the portlet doesn’t appear, add it as described in 8.5, “Deploying the JasperServer Portlet WAR File,” on page 73.

When Liferay connects to JasperServer, JasperServer looks for the Portal organization; it creates this organization if
it doesn’t exist. JasperServer also looks for the user ID; if it is found, JasperServer allows access; if it isn’t found, the
user is created and assigned the ROLE_PORTLET and ROLE_USER roles. If your JasperServer instance hosts
multiple organizations, the user is mapped to the Portal organization.

8.8 JasperServer Portlet Configuration Options

You can configure several parameters that control the JasperServer portlet. They are located in the <liferay-install>/<tomcat-
dir>/webapps/<JasperServerPortlet-x.x.x>/WEB-INF/portlet.xml file. You must restart Liferay for these changes to take
effect.

The values described in this section are case sensitive.

8.8.1 Portlet Parameters

8.8.1.1 portal_server
The only supported value for this parameter is liferay. For example:

<init-param>
<name>portal_server</name>
<value>liferay</value>
</init-param>

8.8.1.2 show_logo
This parameter indicates whether the company logo (at the top right-hand corner of the portlet) is displayed. Any value other
than true hides the logo. For example:

<init-param>
<name>show_logo</name>
<value>true</value>
</init-param>

8.8.1.3 show_return_to_report_list_icon
The parameter indicates whether the Return to Report List icon is displayed. Any value other than true hides the icon. For
example:

<init-param>
<name>show_return_to_report_list_icon</name>
<value>true</value>
</init-param>

75
JasperServer Administrator Guide

8.8.1.4 show_return_to_parameter_icon
The parameter indicates whether the Report Options icon should be shown. Any value other than true hides the icon. For
example:

<init-param>
<name>show_return_to_parameter_icon</name>
<value>true</value>
</init-param>

8.8.1.5 company_logo
This parameter specifies the image to use when show_logo is set to true. The picture must be located under <liferay-
install>/<tomcat-dir>/webapps/<JasperServerPortlet-x.x.x>/WEB-INF/images/. For example:

<init-param>
<name>company_logo</name>
<value>jaspersoft-logo.png</value>
</init-param>

8.8.1.6 company_logo_hyper_link
This parameter specifies the hyperlink URL to request when a user clicks the company logo. For example:

<init-param>
<name>company_logo_hyper_link</name>
<value>http://www.jaspersoft.com</value>
</init-param>

8.8.1.7 report_directory
This parameter specifies a folder in the JasperServer repository that should be used to populate the Report List page in the
portlet. For example:

<init-param>
<name>report_directory</name>
<value>/</value>
</init-param>

8.8.1.8 number_of_reports_per_page
This parameter specifies the pagination limit for the Report List page. It specifies how many reports to display per page. When
there are more reports than the specified number, end users must click a link to go to next page. For example:

<init-param>
<name>number_of_reports_per_page</name>
<value>5</value>
</init-param>

8.8.2 Example Server and Browser Configuration

This section shows examples of the updated files that must be edited to enable Liferay integration with JasperServer.

76
 Integrating JasperServer and Liferay Portal

8.8.2.1 applicationContext-security
By default, this file is found at <js-install>/webapps/jasperserver-pro/WEB-INF/

<property name="trustedIpAddress">
<list>
<value>123.45.6.789</value>
</list>
</property>

You can also use the value localhost or 127.0.0.1 for this property.

8.8.2.2 portlet.xml
Default Location: <liferay-install>/<tomcat-dir>/webapps/<JasperServerPortlet-x.x.x>/WEB-INF/

<init-param>
<name>jasperserver_repository_ws_url</name>
<value>http://123.45.6.789:8080/jasperserver-pro/services/repository</value>
</init-param>

You can also use the value localhost or 127.0.0.1 for this property.

8.8.2.3 Browser URL

Users point their browsers to: http://Liferay_host:7080/c/portal

8.9 Setting up JasperReports Hyperlinks for Use in a Portlet Environment

Because the portal environment is different than that of JasperServer when runs stand-alone, the behavior of links in reports is
also different. Although any valid JasperReports link is rendered within the portal environment, the hyperlinks behave
differently than if the report is run directly in JasperServer. For example, some hyperlinks might become static text when
running within a portal server.

This section assumes you are using iReport 3.7.0 to set up the hyperlinks.

77
JasperServer Administrator Guide

The JasperServer portlet supports these types of links:

Hyperlink Reference Tab Link Parameters Tab ToolTip Tab

Points to an external Hyperlink Reference Expression value Parameters and values that Tooltip for the
URL when the must start with http:// or https://. the target web site receives. hyperlink.
Hyperlink Type is When users click the link within a portlet,
CUSTOM or Reference the current browser window displays the
new web page. The user leaves the portal
environment.
If Hyperlink is invalid, static text is
rendered without links.

Points to a particular Hyperlink Reference Expression value Parameters and values that Tooltip for the
page of the same report specifies the target page number of the the target web site receives. hyperlink.
when the Hyperlink current report. For multiple-valued
Type is LocalPage. parameters, use the same
parameter name for each
parameter value.

Points to a particular Hyperlink Reference Expression is used in Hyperlink Page Expression Tooltip for the
page of a different specification of the target page URI. value specifies the target hyperlink.
report when the page number of the target
Hyperlink Type is report.
RemotePage.

Notes:
Š If type None is chosen, no hyperlink is rendered.
Š For both Hyperlink Target values Self and Blank, the target report is displayed in the same portlet window.
Š For Hyperlink Type RemoteAnchor and LocalAnchor, no links are rendered.

78
 Localization

9 LOCALIZATION

By default, JasperServer is presented in the English language; JasperServer supports other languages in the form of translation
packs that include the data formats and resource bundles for Chinese (Simplified), French, German, Japanese, and Spanish.
These files are included in your JasperServer instance by default; to view the application in a specific locale, select it before
logging in.
If you need to support a language other than the ones JasperServer supports, you can localize JasperServer, including
translating it into a different language by providing labels and messages in the preferred language. For other locales, you may
also want to change the default locale and timezone. This chapter describes the process and discusses a few cases that may
require further configuration.
For information about Domain, Topic, and report localization, refer to the JasperServer User Guide.
This chapter contains the following sections:
Š UTF-8 Configuration
Š Creating a Locale
Š Configuring JasperServer to Offer a Locale
Š Character Encoding and Fonts
Š JasperBabylon

9.1 UTF-8 Configuration

JasperServer uses UTF-8 (8-bit Unicode Transformation Format) character encoding. If your database server or application
server uses a different character encoding form, you may have to configure them to support UTF-8. This section provides
information for configuring the character encoding for several application servers and database servers. If you use a different
application server or database, and its default character encoding isn’t UTF-8, you may need to make similar updates to
support certain locales. For more information, refer to the documentation for your application server or database.

9.1.1 Tomcat
By default, Tomcat uses ISO-8859-1 (ISO Latin 1) character encoding for URIs, which is sufficient for Western European
locales, but does not support many locales in other parts of the world.
If you plan to support locales that Latin 1 does not support, you must change Tomcat’s URI encoding format.

79
JasperServer Administrator Guide

To configure Tomcat to support UTF-8:

1. Open the conf/server.xml file and locate the section that reads:

<!-- Define a non-SSL HTTP/1.1 Connector on port 8080 -->

<Connector port="8080" maxHttpHeaderSize="8192"
maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
enableLookups="false" redirectPort="8443" acceptCount="100"
connectionTimeout="20000" disableUploadTimeout="true" />

2. At the end of this section, insert the following text before the closing marker:

URIEncoding="UTF-8"

3. For example, after your changes, the section might read:

<!-- Define a non-SSL HTTP/1.1 Connector on port 8080 -->

<Connector port="8080" maxHttpHeaderSize="8192"
maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
enableLookups="false" redirectPort="8443" acceptCount="100"
connectionTimeout="20000" disableUploadTimeout="true"
URIEncoding="UTF-8" />

4. Save the file.

5. Restart Tomcat.

9.1.2 JBoss
Since JBoss uses Tomcat as its web connector, it requires you to make the same change to server.xml file as are necessary for
Tomcat (as described in 9.1.1, “Tomcat,” on page 79). In this case, the server.xml file is located in the Tomcat deployment
directory, typically server/default/deploy/jbossweb-tomcat55.sar. After making your changes, restart JBoss.

9.1.3 MySQL
By Default MySQL uses ISO-8859-1 (ISO Latin 1) character encoding. However, JasperServer requires MySQL to use UTF-
8 character encoding for the database that stores its repository as well as for its data sources. The simplest way to meet the
requirement is to create the database with a UTF-8 character set. For example, enter the following command:

create database jasperserver character set utf8;

In addition, the MySQL JDBC driver requires these additional parameter settings to support UTF-8:

useUnicode=true
characterEncoding=UTF-8

Add these to the end of the URL. For example:

url="jdbc:mysql://localhost:3306/jasperserver?useUnicode=true&amp;characterEncoding=
UTF-8"/>

80
 Localization

If the MySQL database is a JNDI data source managed by Tomcat, such as the JasperServer repository database, the
parameters can be added to the JDBC URL in WEB-INF/context.xml. The following is an example resource definition from
that file:

<Resource name="jdbc/jasperserver" auth="Container" type="javax.sql.DataSource"

maxActive="100" maxIdle="30" maxWait="10000"
username="root" password="password" driverClassName="com.mysql.jdbc.Driver"
url="jdbc:mysql://localhost/jasperserver?useUnicode=true&amp;characterEncoding=UTF-8"/>

JBoss ignores the context.xml file, instead requiring an XML file to define JNDI data sources in the deployment directory,
which is typically server/default/deploy. The following is an example of a resource definition in one of those XML files:

<local-tx-datasource>
<jndi-name>jdbc/jasperserver</jndi-name>
<connection-url>
jdbc:mysql://localhost/jasperserver?useUnicode=true&amp;characterEncoding=UTF-8
</connection-url>
<driver-class>com.mysql.jdbc.Driver</driver-class>
<user-name>jasperadmin</user-name>
<password>jasperadmin</password>
<min-pool-size>5</min-pool-size>
<max-pool-size>20</max-pool-size>
<idle-timeout-minutes>0</idle-timeout-minutes>
<metadata>
<type-mapping>mySQL</type-mapping>
</metadata>
</local-tx-datasource>

If the database is a JDBC data source configured in the repository, change the JDBC URL by editing the data source in the
JasperServer repository. The following is an example of the JDBC URL (note that the ampersand isn't escaped):

jdbc:mysql://localhost:3306/foodmart_ja?useUnicode=true&characterEncoding=UTF-8

9.1.4 Oracle
Oracle databases have both a default character set and a national character set that supports Unicode characters. Text types
beginning with N (NCHAR, NVARCHAR2, and NCLOB) use the national character set. As of JasperServer 1.2, all the text
data used by the JasperServer repository (when stored in Oracle) is stored in NVARCHAR2 columns, so that JasperServer
metadata can use the full Unicode character set. For more information about Unicode text support, refer to the Oracle white
paper found at: http://www.oracle.com/technology/tech/globalization/pdf/TWP_NCHAR_MIGRATION_10gR2.pdf
To work properly with Unicode data, the Oracle JDBC driver requires you to set a Java system property by passing the
following argument to the JVM:

-Doracle.jdbc.defaultNChar=true

In Tomcat, add the variable to JAVA_OPTS in bin/setclasspath.sh (Linux) or bin/setclasspath.bat (Windows):

1. Locate the following line in the script:

Linux # Set the default -Djava.endorsed.dirs argument

Windows rem Set the default -Djava.endorsed.dirs argument

81
JasperServer Administrator Guide

2. Add the following line before it:

Linux JAVA_OPTS="$JAVA_OPTS "-Doracle.jdbc.defaultNChar=true

Windows set JAVA_OPTS=%JAVA_OPTS% -Doracle.jdbc.defaultNChar=true

Since JBoss also uses JAVA_OPTS to pass options to the JVM, you can add the same JAVA_OPTS line to bin/run.sh (Linux)
or bin/run.bat (Windows). The line must be added before this line:

Linux # Setup the java endorsed dirs

Windows rem Setup the java endorsed dirs

9.2 Creating a Locale

Translation is only one aspect of localization. Creating a locale includes these tasks:
Š Translating labels and messages.
Š Changing date formats.
Š Changing format masks.

The tasks in this section require you to edit these files:

File Name Location Purpose of Edits

*.properties files WEB-INF\bundles Translating labels and messages

jasperserver_config.properties WEB-INF\bundles Changing date formats

adhoc_masks WEB-INF\bundles Changing format masks

9.2.1 About Properties Files

JasperServer and JasperAnalysis resource bundle files are found in the WEB-INF/bundles directory. JasperServer includes
a default locale (for example, jasperserver_messages.properties), which is written in the U.S. English dialect.
A resource bundle consists of the *.properties files that contain all the labels and messages used in the JasperServer and
JasperAnalysis, customized for a particular locale. The default resource bundle includes these files:

Component Default File Name Description

JasperServer adhoc_messages.properties Labels and messages specific to JasperServer
Professional and Enterprise; includes text for the Ad
Hoc Editor.

JasperServer jasperserver_messages.properties Core labels and messages used in JasperServer.

JasperServer pro_nav_messages.properties Labels and messages specific to JasperServer

Professional and Enterprise; includes text for the
Home page and menu bar.

JasperServer LicenseMessages.properties Labels and messages used by JasperServer when

validating licenses.

JasperServer jasperserver_config.properties Configuration properties for dates and date times.

JasperServer calendar.properties Labels and messages used by the calendar control.

JasperAnalysis ja_mondrian.properties Labels and messages used in JasperAnalysis.

82
 Localization

Component Default File Name Description

JasperAnalysis ja-pro_messages.properties Labels and messages specific to JasperAnalysis
Professional and Enterprise; includes text for the
Professional and Enterprise user interface.

JasperAnalysis jpivot_messages.properties Labels and messages used in JasperAnalysis.

JasperAnalysis Mondrian_exception_messages. MDX validation error messages specific to the internal

properties analysis engine.

If you use the JasperServer portlet to display JasperServer content in a portal (such as Liferay), the deployed portlet includes
properties files as well:

Default File Name Location Description

jaspersoft_portlet_message. WEB-INF\bundles under the location where the Labels and messages that
properties portlet is deployed. For example: appear in the portlet, including
C:\liferay\webapps\<portlet_context_name>\WEB- the help text.
INF\bundles (where <portlet_context_name> is Note that this does not include
the name specified when the JasperServer portlet text in specific reports; to localize
was deployed). the report’s content, you must
upload its resource bundle to the
repository.

iReport and the iReport plugin have their own resource bundles, including:

Component Default File Name Description

iReport ireport.properties Labels and messages used in iReport.

iReport plugin irplugin.properties Labels and messages used in the JasperServer iReport plugin.

Jaspersoft recommends using JasperBabylon to localize iReport and the iReport plugin resource bundles. For more
information, refer to 9.5, “JasperBabylon,” on page 90.

9.2.2 Creating a Resource Bundle

Create a resource bundle by making a copy of each *.properties file, using the following syntax for the copy’s file name:
<default_file_name>_<locale>.properties,
where
<default_file_name> is the name of the default version of the properties file, and
<locale> is a Java-compliant locale identifier.
For example, consider the core JasperServer resource bundle. For various locales, it might be named:

File Type File Name

Default resource bundle jasperserver_messages.properties

English jasperserver_messages_en.properties

French jasperserver_messages_fr.properties

French in Switzerland jasperserver_messages_fr_CH.properties

For a list of Java-compliant locales, please refer to Sun’s Java web site.

83
JasperServer Administrator Guide

The resource bundles described in this document consist of locale-specific Java properties files. Java properties files
use the ISO-8859-1 (Latin-1) encoding that is the same as ASCII for all English non-accented characters. For
international characters that are not in ISO-8859-1, use Unicode escape sequences (for example \u00e9 is é).

To create a new JasperServer resource bundle:

1. Copy each of the properties files (keeping them in the same directory as the originals) and rename them according to your
locale.
2. Translate each *.properties file’s labels and messages into the new language.
Some of the strings in the properties files may not seem like English. These cases are typically date formats and format
masks that may need to be edited for the new locale. For more information, refer to 9.2.3, “Changing Format Masks and
Date Formats,” on page 84.
3. Save the files.
4. If the new locale requires specific character encoding or fonts, ensure that JasperServer and the third party software it
relies on are configured to support them. For more information, refer to 9.4, “Character Encoding and Fonts,” on
page 88.

This locale will not be available in JasperServer until you follow the steps described in 9.3.1, “Specifying Additional
Locales,” on page 86.

9.2.3 Changing Format Masks and Date Formats

Each locale may have its own format masks and rules for displaying dates and datetime values. This section describes the steps
you must take to update these options for your new locale.

The data format masks described in this section are used in the Domains and in the Ad Hoc Editor; they appear in Ad
Hoc reports as well as JRXML reports based on Domains; they are not applicable to JasperAnalysis.

9.2.3.1 Changing Date and Datetime Formats

System date and datetime formatting is controlled by four patterns that are specified in the
jasperserver_config_<locale>.properties file associated with a particular locale.
For example in the English resource bundle, the four entries are:

date.format=dd-MM-yyyy
datetime.format=dd-MM-yyyy HH:mm
calendar.date.format=%d-%m-%Y
calendar.datetime.format=%d-%m-%Y %H:%M

The first two keys are used to parse and format dates and datetime values using an internal java.util.DateFormat
object across the whole application. These patterns should be non-localized date patterns, in accordance with the Java
Development Kit (JDK) syntax.
The other two keys are used by the calendar control, which formats the user-selected date and datetime values in accordance
with its own pattern syntax.
To change the system date and datetime formatting for a new locale, edit the strings specified by these keys.

9.2.3.2 Changing Data Format Masks

The Ad Hoc Editor allows you to create custom reports based on a Topic or Domain. Such reports support localizable data
format masks that determine how values appear. To make the data format masks vary by locale, you must create an
adhoc_masks file for the new locale. To do so, copy the default file (adhoc_masks.properties) to a new name that specifies the
new locale (for example, the Hungarian file would be named adhoc_masks_hu.properties), and change the masks defined in
the new file.

84
 Localization

Customize the available data format masks for dates, integers, and decimals by editing the existing masking entries or adding
new ones. The default entries are given in the following table:

Data Format Mask Properties Appearance in en_US Locale

ADH_100_MASK_date_0 = short,hide 3/31/09
ADH_100_MASK_date_1 = long,hide Mar 31, 2009
ADH_100_MASK_date_2 = short,medium March 31, 2009
ADH_100_MASK_date_3 = medium,medium Mar 31, 2009 23:59:59

ADH_100_MASK_int_0 = #,##0 -1,234

ADH_100_MASK_int_1 = 0 -1234
ADH_100_MASK_int_2 = $#,##0;($#,##0) ($1,234)
ADH_100_MASK_int_3 = #,##0;(#,##0) (1234)

ADH_100_MASK_dec_0 = #,##0.00 -1,234.56

ADH_100_MASK_dec_1 = 0 -1234
ADH_100_MASK_dec_2 = $#,##0.00;($#,##0.00) ($1,234.56)
ADH_100_MASK_dec_3 = $#,##0;($#,##0) ($1,234)

ADH_101_EXAMPLE_NUMBER = -1234.56

The data format masks for each type are numbered consecutively from zero; create new masks by adding new entries. The
keys of the new entries must follow the convention established in the default entries. For example, a new decimal data format
mask might have this ID:

ADH_100_MASK_dec_4

Date format masks are implemented using java.text.SimpleDateFormat and JasperReports extensions that provide
access to predefined localized data format masks. New datetime masks must be specified in one of the following formats:
Š A style for the date part of the value and a style for the time part (separated by comma) or a single style for both parts. A
style is one of Short, Medium, Long, Full, Default (which correspond to java.text.DateFormat styles) and Hide.
Š A pattern that can be supplied to java.text.SimpleDateFormat. In this case, internationalization support is limited.
Both integer and decimal data format masks are implemented with java.text.DecimalFormat, which localizes characters
within the format specification. For example, consider the case of the digit grouping symbol (thousands separator): in French,
it is a space; in U.S. English, it is a comma. DecimalFormat handles both cases: if the number pattern #,##0 is used, the
number 6000 appears as 6 000 in the French locale and as 6,000 in the U.S. English locale.
Form more information about Java’s handling of decimal and date data format masks, refer to Sun’s website:
Š http://java.sun.com/j2se/1.5/docs/api/java/text/DecimalFormat.html
Š http://java.sun.com/j2se/1.5/docs/api/java/text/DateFormat.html

By default, monetary values in Ad Hoc reports are masked as USD (United States Dollars). Depending on your data,
you may need to support a different currency, support more than one currency, or support currency conversion.
These are three very different cases:
Š Supporting a different currency than USD involves changing the monetary masks to use the correct symbol for your
currency (for example, replace the $ symbol in the ADH_100_MASK_dec_2 and ADH_100_MASK_dec_3 masks).
However, changing this symbol does not actually convert currencies in your reports.
Š Supporting other currencies in addition to USD involves adding new masks. However, adding data formats does not
actually convert currencies in your reports.
Š Supporting currency conversion is more complicated; you must consider such issues as fluctuations in conversion
rates. Oftentimes, a third-party services can be used to perform currency conversion

85
JasperServer Administrator Guide

9.3 Configuring JasperServer to Offer a Locale

After creating a locale, you must configure JasperServer to offer it to your users, along with any new time zones.
The tasks in this section require you to edit these files:

File Name Location Purpose of Edits

applicationContext-security.xml WEB-INF Specifying additional locales

jasperserver-servlet.xml WEB-INF Specifying additional time zones

9.3.1 Specifying Additional Locales

By default, JasperServer appears in the locale selected in the end user’s browser. The Login page allows users to specify the
locale they want to use in JasperServer. The list of locales from which they choose is defined in applicationContext-
security.xml. Edit this file to add a new locale.

To add a new locale:

1. Edit the applicationContext-security.xml file and locate the bean named userLocalesList. For example:

<bean id="userLocalesList"
class="com.jaspersoft.jasperserver.war.common.LocalesListImpl">
<property name="locales">
<list>
<value type="java.util.Locale">en</value>
<value type="java.util.Locale">fr</value>
<value type="java.util.Locale">it</value>
<value type="java.util.Locale">de</value>
<value type="java.util.Locale">ro</value>
<value type="java.util.Locale">ja</value>
<value type="java.util.Locale">zh_TW</value>
</list>
</property>
</bean>

2. Add the new locale to the end of the list. For example, add the following line for Dutch (Java’s nl_NL locale):

<value type="java.util.Locale">nl_NL/value>

3. Save the file.

4. Restart JasperServer, and log into the web application to test your translation. Reviewing the translated strings in context
can help you improve your word choices.
For a list of Java-compliant locales, please refer to Sun’s Java web site.

9.3.2 Specifying Additional Time Zones

By default, JasperServer assumes the user’s time zone is the same as the time zone of the JasperServer host. However, the
Login page allows users to choose a different time zone. The list from which they choose is defined in application-context.xml
file.

86
 Localization

To add a time zone:

1. Open the application-context.xml file and locate the userTimeZonesList bean. For example:

<bean id="userTimeZonesList"
class="com.jaspersoft.jasperserver.war.common.JdkTimeZonesList">
<property name="timeZonesIds">
<list>
<value>America/Los_Angeles</value>
<value>America/Denver</value>
<value>America/Chicago</value>
<value>America/New_York</value>
<value>Europe/London</value>
<value>Europe/Berlin</value>
<value>Europe/Bucharest</value>
</list>
</property>
</bean>

2. Add the new time zone to the bottom of the list. Specify each time zone as the standard Java time zone values so that
JasperServer adjusts for daylight savings time when appropriate. For example, add the following line for Tokyo:

<value>Asia/Tokyo</value>

3. Save the file.

4. Restart JasperServer.
For more information about Java-complaint time zones, please refer to Sun’s Java web site.

9.3.3 Setting a Default Time Zone

If you want JasperServer to use a time zone that is different from the host computer, you can set a specific time zone in Java. It
becomes the default time zone for all users, but they may still select a different time zone when they log in.
To set a default time zone, set the user.timezone property in the JVM as shown in the tables below. Locate the file
containing JVM settings for your platform and application server. The value for the property must be a Java-compliant time
zone, for example Europe/Bucharest.

JVM Options on Windows

Tomcat file <apache-tomcat>\bin\setenv.bat

JBoss file <jboss>\bin\run.bat

Add new line set JAVA_OPTS=%JAVA_OPTS% -Duser.timezone=Europe/Bucharest

JVM Options on Linux

Tomcat file <apache-tomcat>/bin/setenv.sh

JBoss file <jboss>/bin/run.sh

Add new line export JAVA_OPTS="$JAVA_OPTS -Duser.timezone=Europe/Bucharest"

87
JasperServer Administrator Guide

JVM Options for Glassfish (Windows and Linux)

Glassfish file <glassfish>/domains/domain1/config/domain.xml

Add to -Duser.timezone=Europe/Bucharest
<jvm-options>

You must restart your application server for this setting to take effect. The time zone will be set for all applications in your
application server, including JasperServer.

9.4 Character Encoding and Fonts

Depending on the third-party software you use and the locales you support, you may also have to configure JasperServer and
its host. The steps described in this section are only necessary under certain circumstances, such as if you plan to use a
character encoding form that UTF-8 cannot handle, or if you need to change the font options for JasperAnalysis charts.
The tasks in this section require you to edit these files:

File Name Location Purpose of Edits

applicationContext.xml WEB-INF Changing character encoding

jpivot_internal_messages.properties WEB-INF/internal Specifying chart fonts for JasperAnalysis

Community

Ja_pro_internal_messages.properties WEB-INF/internal Specifying chart fonts for JasperAnalysis

Professional and Enterprise

userConfig.xml WEB-INF/jpivot/print Embedding fonts in PDF

9.4.1 Changing Character Encoding

To use a character encoding form other than UTF-8, you must configure JasperServer, your application server, and your
database server.

9.4.1.1 Configuring JasperServer

To configure JasperServer to use a different encoding form, you must edit the applicationContext.xml file.

To specify a different encoding form:

1. Open the applicationContext.xml file and locate the following bean:

<bean id="encodingProvider"
class="com.jaspersoft.jasperserver.api.common.util.StaticCharacterEncodingProvider">
constructor-arg value="UTF-8"/>
</bean>

2. Change UTF-8 to the encoding type your database server and application server use. For example:

<bean id="encodingProvider"
class="com.jaspersoft.jasperserver.api.common.util.StaticCharacterEncodingProvider">
constructor-arg value="UTF-16"/>
</bean>

3. Save the file.

4. Restart JasperServer.

88
 Localization

9.4.1.2 Configuring the Application Server and Database Server

If you want to use a character encoding form other than UTF-8, you may need to configure the third party software that
JasperServer relies on. For more information, refer to the documentation associated with your application server and database
server. For Tomcat, you can specify a different character encoding by following steps similar to those described in 9.1.1,
“Tomcat,” on page 79 and 9.1, “UTF-8 Configuration,” on page 79.

This step is necessary only if you plan to support locales that requires a different character encoding, such as
UTF-16. In addition to this change, your application server and database must be configured to use the character
encoding you require. For more information, refer to the documentation associated with your third party software.

9.4.1.3 Configuration for Localized Analysis Schemas

If you plan to use localized analysis views, you must take additional steps to configure JasperServer.

To configure JasperServer for localized analysis views:

1. Every Unicode database that JasperServer interacts with (whether it is the repository database or a database accessed
through a data source defined in JasperServer) must be created to support UTF-8. For example, to create the Foodmart
database in MySQL, you might give a command similar to:

create database foodmart_ja character set utf8;

2. The URL of any OLAP database that JasperServer accesses must be properly configured in the /ji-pro/META-INF/
context.xml file. For example, the URL definition for the Foodmart sample database might be similar to the following:

<Resource name="jdbc/MondrianFoodMart_ja" auth="Container" type="javax.sql.DataSource"

maxActive="100" maxIdle="30" maxWait="10000"
username="root" password="password" driverClassName="com.mysql.jdbc.Driver"
url="jdbc:mysql://localhost:3306/foodmart _ja?
useUnicode=true&amp;characterEncoding=UTF-8"/>

3. Encoding options must be added to the JDBC connection string for any data source that points to an OLAP database. For
example, when creating a data source in JasperServer that points to an OLAP database, use the following connection
string:

jdbc:mysql://localhost:3306/foodmart_ja? useUnicode=true&characterEncoding=UTF-8

9.4.2 Working with Fonts

While the fonts JasperServer uses are generally dictated by the JRXML files that define your reports, some font configuration
is required for special circumstances. For example, you can configure JasperAnalysis to offer different options in the Chart
Default Font field in the Chart Options window. In order to use a font in JasperServer, the font must be available in the host’s
operating system.
This section describes steps you may need to take, depending on the functionality you use and the locales you support.

9.4.2.1 Configuring Options for Chart Default Fonts

If you implement JasperAnalysis and support a locale with special font requirements, you can configure JasperAnalysis to
offer different options in the Chart Default Font field in the Chart Options window of the analysis view. This may be
necessary if you implement locales that Latin 1 doesn’t support.
An analysis view’s Chart Options window includes the Chart Default Font field, which allows users to select the font to use
in charts. The default options are SansSerif, Serif, and MonoSpaced. JasperServer reads these values from a properties file and
attempts to map them to fonts available in the JasperServer host’s operating system. You can configure JasperServer to offer
different fonts if these fonts don’t support the locales you implement.

89
JasperServer Administrator Guide

To change the Chart Default Font field’s options:

1. Copy the jpivot_internal_messages.properties file, and copy it to a new name that reflects the new locale. For example, for
Japanese, the new file would be called jpivot_internal_messages_ja.properties.
2. Open the new file and locate the following keys:

JAJ_000_jsp.jpivot.chartpropertiesform.sansSerif=SansSerif
JAJ_000_jsp.jpivot.chartpropertiesform.serif=Serif
JAJ_000_jsp.jpivot.chartpropertiesform.monospaced=Monospaced

If you are using JasperAnalysis Community Edition, the name of the file and the keys that you edit are different.
For the Community Edition, open the jpivot_internal_message.properties file and edit these keys:
jsp.wcf.chart.sansserif=SansSerif
jsp.wcf.chart.serif=Serif
jsp.wcf.chart.monospaced=Monospaced

3. Change one or more of the strings to the name of a font available in the host’s operating system. For example, if you
wanted to change the SansSerif font to the SimHei font, edit the value specified by jsp.wcf.chart.sansserif. For
example:

jsp.wcf.chart.sansserif=SimHei

4. Save the file.

5. Restart JasperServer.

9.4.2.2 Embedding Fonts in PDF Output

By default, JasperServer can create PDF (Portable Document Format) files with many different fonts. However, if you
experience font problems in the PDF output of your reports, you may need to take the steps described in this section
to make the fonts available to JasperServer’s XSL Formatting Object (XSL-FO) processor.

When users save reports in PDF format, JasperServer generates the PDF output using Apache FOP (Formatting Objects
Processor). In order for FOP to render fonts properly, you must install the font itself (for example, a TTF file) on the
JasperServer host, create a font metrics file (using Apache’s org.apache.fop.fonts.apps.TTFReader utility), and
update the userConfig.xml file to associate the font with its metrics. For more information, refer to the documentation
associated with FOP, which is available at:
http://xmlgraphics.apache.org/fop/
You can embed any Unicode font using this procedure, though larger font files may have significantly larger memory
footprints. In order to keep memory requirements small, Jaspersoft recommends that you use the smallest font file you can,
such as SimHei to support Chinese, Japanese, and Korean.
You must have the distribution rights to a font in order to embed it in a PDF file.

9.5 JasperBabylon
JasperBabylon allows Jaspersoft’s open source community to edit and share locale resource bundles. The repository is public,
and includes translations for several applications (notably, iReport, iReport plugin, and the open source version of
JasperServer). You can access the repository by pointing your browser to the JasperBabylon web site:
http://www.jasperforge.org/jasperbabylon
More information, including usage instructions, is available on the JasperBabylon web site. To make updates on this site, you
must sign up for a contributor ID, which is free.

90
 Glossary

GLOSSARY

Ad Hoc Editor
JasperServer’s integrated report designer. Starting from a collection of fields predefined in a Topic or selected from a Domain,
the Ad Hoc Editor lets you drag and drop report elements to draft, preview, and finalize reports. Like JRXML reports, Ad Hoc
reports can be run, printed, and scheduled within JasperServer. In addition, Ad Hoc reports may be reopened in the Ad Hoc
Editor, further modified, and saved.
Analysis Client Connection
A definition for retrieving an analysis view. An analysis client connection is either a direct Java connection (Mondrian
connection) or an XML-based API connection (XMLA connection).
Analysis Schema
A metadata definition of a multidimensional database. In JasperAnalysis, schemas are stored in the repository as XML file
resources.
Analysis View
A view of multidimensional data that is based on an analysis client connection and an MDX query. It is the entry point to
analysis operations, such as slice and dice, drill down, and drill through.
Calculated Field
In a Domain, a field whose value is calculated from a user-written formula that may include any number of fields, operators,
and constants. A calculated field is defined in the Domain Designer dialog, and it becomes one of the items to which the
Domain’s security file and locale bundles can apply.
CRM
Customer Relationship Management. The practice of managing every facet of a company’s interactions with its clientele.
CRM applications help businesses track and support their customers.
CrossJoin
An MDX function that combines two or more dimensions into a single axis (column or row).
Cube
The basis of most analysis applications, a cube is a data structure that contains three or more dimensions that categorize the
cube’s quantitative data. When you navigate the data displayed in an analysis view, you are exploring a cube.

91
JasperServer Administrator Guide

Custom Field
In the Ad Hoc Editor, a field that is created through menu items as a simple function of one or two available fields, including
other custom fields. When a custom field becomes too complex or needs to be used in many reports, it is best to define it as a
calculated field in a Domain.
Dashboard
A collection of reports, input controls, graphics, labels, and web content displayed in a single, integrated view. Dashboards
often present a high level view of your data, but input controls can parameterize the data to display. For example, you can
narrow down the data to a specific date range. Embedded web content, such as other web-based applications or maps, make
dashboards more interactive and functional.
Derived Table
In a Domain, a derived table is defined by an additional query whose result becomes another set of items available in the
Domain. For example, with a JDBC data source, you can write an SQL query that includes complex functions for selecting
data. You can use the items in a derived table for other operations on the Domain, such as joining tables, defining a calculated
field, or filtering. The items in a derived table can also be referenced in the Domain’s security file and locale bundles.
Data Policy
In JasperServer, a setting that determines how JasperServer should process and cache data used by Ad Hoc reports. Select your
data policies by clicking Manage > Ad Hoc Options.
Data Source
Defines the connection properties that JasperServer needs to access data. JasperServer transmits queries to data sources and
obtains datasets in return for use in filling reports and previewing Ad Hoc reports. JasperServer supports JDBC, JNDI, and
Bean data sources; custom data sources can be defined as well.
Dataset
A collection of data arranged in columns and rows. Datasets are equivalent to relational results sets and the JRDataSource
type in JasperReports.
Datatype
In JasperServer, a datatype is used to characterize a value entered through an input control. A datatype must be of type text,
number, date, or date-time. It can include constraints on the value of the input, for example maximum and minimum values.
As such, a JasperServer datatype is more structured than a datatype in most programming languages.
Denormalize
A process for creating table joins that speeds up data retrieval at the cost of having duplicate row values between some
columns.
Dice
An OLAP operation to select columns.
Dimension
A categorization of the data in a cube. For example, a cube that stores data about sales figures might include dimensions such
as time, product, region, and customer’s industry.
Domain
A virtual view of a data source that presents the data in business terms, allows for localization, and provides data-level
security. A Domain is not a view of the database in relational terms, but it implements the same functionality within
JasperServer. The design of a Domain specifies tables in the database, join clauses, calculated fields, display names, and
default properties, all of which define items and sets of items for creating Ad Hoc reports.
Domain Topic
A Topic that is created from a Domain by the Choose Ad Hoc Data wizard. A Domain Topic is based on the data source and
items in a Domain, but it allows further filtering, user input, and selection of items. Unlike a JRXML-based Topic, a Domain
Topic can be edited in JasperServer by users with the appropriate permissions.

92
 Glossary

Drill
To click on an element of an analysis view to change the data that is displayed:
Š Drill down. An OLAP operation that exposes more detailed information down the hierarchy levels by delving deeper into
the hierarchy and updating the contents of the navigation table.
Š Drill through. An OLAP operation that displays detailed transactional data for a given aggregate measure. Click a fact to
open a new table beneath the main navigation table; the new table displays the low-level data that constitutes the data that
was clicked.
Š Drill up. An OLAP operation for returning the parent hierarchy level to view to summary information.
Eclipse
An open source Integrated Development Environment (IDE) for Java and other programming languages, such as C/C++.
ETL
Extract, Transform, Load. A process that retrieves data from transactional systems, and filters and aggregates the data to create
a multidimensional database.
Fact
The specific value or aggregate value of a measure for a particular member of a dimension. Facts are typically numeric.
Field
A field is equivalent to a column in the relational database model. Fields originate in the structure of the data source, but you
may define calculated fields in a Domain or custom fields in the Ad Hoc Editor. Any type of field, along with its display name
and default formatting properties, is called an item and may be used in the Ad Hoc editor.
Frame
A dashboard element that displays reports or custom URLs. Frames can be mapped to input controls if their content can accept
parameters.
Group
In a report, a group is a set of data rows that have an identical value in a designated field.
Š In a table, the value appears in a header and footer around the rows of the group, while the other fields appear as columns.
Š In a chart, the field chosen to define the group becomes the independent variable on the X axis, while the other fields of
each group are used to compute the dependent value on the Y axis.
Hierarchy Level
In analysis, a member of a dimension containing a group of members.
Input Control
A button, check box, drop-down list, text field, or calendar icon that allows users to enter a value when running a report or
viewing a dashboard that accepts input parameters. For JRXML reports, input controls and their associated datatypes must be
defined as repository objects and explicitly associated with the report. For Domain-based reports that prompt for filter values,
the input controls are defined internally. When either type of report is used in a dashboard, its input controls are available to be
added as special content.
Item
When designing a Domain or creating a Topic based on a Domain, an item is the representation of a database field or a
calculated field along with its display name and formatting properties defined in the Domain. Items can be grouped in sets and
are available for use in the creation of Ad Hoc reports.
JavaBean
A reusable Java component that can be dropped into an application container to provide standard functionality.
JDBC
Java Database Connectivity. A standard interface that Java applications use to access databases.

93
JasperServer Administrator Guide

JNDI
Java Naming and Directory Interface. A standard interface that Java applications use to access naming and directory services.
Join Tree
In Domains, a collection of joined tables from the actual data source. A join is the relational operation that associates the rows
of one table with the rows of another table based on a common value in given field of each table. Only the fields in a same join
tree or calculated from the fields in a same join tree may appear together in a report.
JPivot
An open source graphical user interface for OLAP operations. For more information, visit http://jpivot.sourceforge.net/.
MDX
Multidimensional Expression Language. A language for querying multidimensional objects, such as OLAP (On Line
Analytical Processing) cubes, and returning cube data for analytical processing. An MDX query is the query that determines
the data displayed in an analysis view.
Measure
Depending on the context:
Š In a report, a formula that calculates the values displayed in a table’s columns, a crosstab’s data values, or a chart’s
dependent variable (such as the slices in a pie).
Š In an analysis view, a formula that calculates the facts that constitute the quantitative data in a cube.
Mondrian
A Java-based, open source multidimensional database application.
Mondrian Connection
An analysis client connection that consists of an analysis schema and a data source used to populate an analysis view.
Mondrian Schema Editor
An open source Eclipse plugin for creating Mondrian analysis schemas.
Mondrian XMLA Source
A server-side XMLA source definition of a remote client-side XMLA connection used to populate an analysis view using the
XMLA standard.
MySQL
An open source relational database management system. For information, visit http://www.mysql.com/.
Navigation Table
The main table in an analysis view that displays measures and dimensions as columns and rows.
Object
In JasperServer, anything residing in the repository, such as an image, file, font, data source, topic, domain, report element,
saved report, report output, dashboard, or analysis view. The folders that contain repository objects are also objects.
Administrators set user and role-based access privileges on repository objects to establish a security policy.
OLAP
On Line Analytical Processing. Provides multidimensional views of data that help users analyze current and past performance
and model future scenarios.
Organization
A set of users that share resources and repository objects in JasperServer. An organization has its own user accounts, roles, and
root folder in the repository to securely isolate it from other organizations that may be hosted on the same instance of
JasperServer.

94
 Glossary

Organization Admin
Also called the organization administrator. A user in an organization with the privileges to manage the organization’s user
accounts and roles, repository permissions, and repository content. An organization admin can also create sub-organizations
and mange all of their accounts, roles, and repository objects. The default organization admin in each organization is the
jasperadmin account.
Outlier
A fact that seems incongruous when compared to other member’s facts. For example, a very low sales figure or a very high
number of helpdesk tickets. Such outliers may indicate a problem (or an important achievement) in your business.
JasperAnalysis excels at revealing outliers.
Parameter
Named values that are passed to the engine at report-filling time to control the data returned or the appearance and formatting
of the report. A report parameter is defined by its name and type. In JasperServer, parameters can be mapped to input controls
that users can interact with.
Pivot
To rotate a crosstab such that its row groups become columns groups and its column groups become rows. In the Ad Hoc
Editor, pivot the crosstab by clicking .

Pivot Table
A table with two physical dimensions (for example, X and Y axis) for organizing information containing more than two
logical dimensions (for example, PRODUCT, CUSTOMER, TIME, and LOCATION), such that each physical dimension is
capable of representing one or more logical dimensions, where the values described by the dimensions are aggregated using a
function such as SUM.
Pivot tables are used in JasperAnalysis.
Properties
Settings associated with an object. The settings determine certain features of the object, such as its color and label. Properties
are normally editable. In Java, properties can be set in files listing objects and their settings.
Repository
The tree structure of folders that contain all saved reports, dashboards, analysis views, and resources. Users access the
repository through the JasperServer web interface or through iReport. Applications can access the repository through the web
service API. Administrators use the import and export utilities to back up the repository contents.
Role
A security feature of JasperServer. Administrators create named roles, assign them to user accounts, and then set access
permissions to repository objects based on those roles. JasperServer also makes certain functionality available to users based
on their roles, which determines certain menu options displayed to those users.
Schema
A logical model that determines how data is stored. For example, the schema in a relational database is a description of the
relationships between tables, views, and indexes. In JasperAnalysis, an OLAP schema is the logical model of the data that
appears in an analysis view; they are uploaded to the repository as resources. For Domains, schemas are represented in XML
design files.
Set
In Domains and Domain Topics, a named collection of items grouped together for ease of use in the Ad Hoc Editor. A set can
be based on the fields in a table or entirely defined by the Domain creator, but all items in a set must originate in the same join
tree. The order of items in a set is preserved.
Slice
An OLAP operation for filtering data rows.

95
JasperServer Administrator Guide

SQL
Structured Query Language. A standard language used to access and manipulate data and schemas in a relational database.
System Admin
Also called the system administrator. A user who has unlimited access to manage all organizations, users, roles, repository
permissions, and repository objects across the entire JasperServer instance. The system admin can create root-level
organizations and manage all server settings. The default system admin is the superuser account.
Topic
A JRXML file created externally and uploaded to JasperServer as a basis for Ad Hoc reports. Topics are created by business
analysts to specify a data source and a list of fields with which business users can create reports in the Ad Hoc Editor. Topics
are stored in the Ad Hoc Components folder of the repository and displayed when a user launches the Ad Hoc Editor.
Transactional Data
Data that describe measurable aspects of an event, such as a retail transaction, relevant to your business. Transactional data are
often stored in relational databases, with one row for each event and a table column or field for each measure.
User
Depending on the context:
Š A person who interacts with JasperServer to fulfill a goal. There are generally three categories of users: administrators
who install and configure JasperServer, database experts or business analysts who create data sources and Domains, and
business users who create and view reports and dashboards.
Š A user account created for a specific person or purpose. The account associates the login name with user's full name,
password, and email address. Roles are assigned to user accounts to determine access to objects in the repository.
WCF
Web Component Framework. A low-level GUI component of JPivot. For more information, see http://jpivot.sourceforge.net/
wcf/index.html.
XML
eXtensible Markup language. A standard for defining, transferring, and interpreting data for use across any number of XML-
enabled applications.
XML/A
XML for Analysis. An XML standard that uses Simple Object Access protocol (SOAP) to access remote data sources. For
more information, see http://www.xmla.org/
XML/A Connection
A type of analysis client connection that consists of Simple Object Access Protocol (SOAP) definitions used to populate an
analysis view.

96
 Index

INDEX
A custom data source
access control 33, 34 and required software 57
Ad Hoc Dataset caching 49 creating 58
Ad Hoc reports 47, 49, 65 examples 56
administering JasperServer installing 61
Ad Hoc options 47 installing the examples 57
assigning roles to users 23 message catalogs 59, 61
assigning users to roles 19, 23 overview of examples 55
audit logging 63 Spring configuration 60
authenticating users 33 using 61
authorizing users 34 D
creating roles 23 data policies 48
crosstab limit 51 datasets 48
custom data sources 55 date formats 84
data policies for Ad Hoc reports 48 Domains
default roles 22 audit logging 65
default users 19 validation 50
Domain validation 50
granting object-level permissions 36 E
heartbeat 52 events in audit logging 63
JasperReports options 50 export utility 42
logging in as a user 38 F
Login page 47 folder
managing access control 33, 34 copy 30
managing the Ad Hoc cache 48 delete 32
passwords 46 move 31
query row limit 47 Folder Template 10, 39
query time out 47 format masks 84
report schedule intervals 52 G
system configuration 45–62 glossary 91
Ant 57
audit logging 63 H
heartbeat program 12, 52
C
cache 48 I
CLOB support 54 import utility 41
configuring the system 45, 63 internationalization 79
crosstab report Out of Memory errors 51 intervals for report schedules 52

97
JasperServer Administrator Guide

J configuration parameters 75
JasperAnalysis 22 deploying 73
JasperBabylon 90 integrating Liferay 71
JasperETL 69 port numbers 71
JBoss 80 report list 74
JDK and JVM 57 testing 74
js-export command 42 properties files
js-import command 41 creating 82
L locale bundles 83
license expiration 13 R
Liferay 71 report scheduling 52
locale bundles repository
configuring JasperServer for 86 copy folder or resource 30
creating a locale 82 delete folder or resource 32
date formats 84 importing and exporting 41
format masks 84 move folder or resource 31
JasperBabylon 90 roles
properties files 82 assigning roles to users 22, 75
localization assigning users to roles 23
fonts 89, 90 audit logging 66
JasperBabylon 90 creating roles 23
localized analysis views 89 default roles 22
non-UTF-8 character encoding 88 granting object-level permissions 36
UTF-8 configuration 79 S
logging 63 search
login 12 configuring search 62
Login page, changing 47 SuperMart demo 19, 22
M superuser 12
managing JasperServer. See administering JasperServer. support, finding product version 13
MySQL 48, 80 synonyms 53
N system administrator. See administering JasperServer.
NVARCHAR2 55 T
O Talend Integration Suite 69
object-level permissions for roles 36 time zone on Login page 86
Oracle 81 Tomcat 79
NVARCHAR2 55 U
synonyms 53 Unicode Transformation Format. See UTF-8.
Organizations folder 10, 39 users
Out of Memory errors 51 assigning roles to users 19, 22
P assigning users to roles 19, 23
passwords audit logging 66
allowing users to change 46 authenticating users 33
audit logging 66 authorizing users 34
expiration 46 granting object-level permissions 36
port numbers 71 UTF-8
portlet encoding forms 88
and hyperlinks in reports 77 non-UTF-8 character encoding 88
and JasperServer roles 22 overview 79
and multiple organizations 75 V
and upgrading JasperServer 73 version of the software 13
and web services 72 W
changing the default report list 76 web services 65, 72
changing the logo 75, 76

98