Jasper Server 3.7.0 User Guide[1]

JASPERSERVER USER GUIDE

RELEASE 3.7

http://www.jaspersoft.com

http://www.jaspersoft.com/

http://www.jaspersoft.com

JasperServer User Guide

© 2010 Jaspersoft Corporation. All rights reserved. Printed in the U.S.A. Jaspersoft, the Jaspersoft logo, JasperAnalysis, JasperServer, JasperETL, JasperReports, 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-10 of the JasperServer User Guide.

2

Table of Contents

TABLE OF CONTENTS

1 Introduction to JasperServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71.1 Logging In . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81.2 The Home Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81.3 Searching the Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

1.3.1 Searching by Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111.3.2 Navigating the Folder Tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111.3.3 Refining With Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121.3.4 Changing the Search Expression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131.3.5 Interacting With the List of Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

2 Working with Dashboards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152.1 Viewing a Dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162.2 Creating a Dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

2.2.1 Dashboard Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172.2.2 Creating a Simple Dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182.2.3 Adding Controls to a Dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192.2.4 Adding a Custom URL to a Dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202.2.5 Refining a Dashboard’s Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212.2.6 Tips for Designing Dashboards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.2.7 About Screen Sizes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

2.3 Editing a Dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242.4 Designing Reports for Dashboards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

3 Running Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273.1 Running a Simple Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273.2 Running a Flash Chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293.3 Running a Report with Input Controls or Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

3.3.1 Simple Input Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303.3.2 Cascading Input Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

3.4 Scheduling Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

3


3.4.1 Viewing Scheduled Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343.4.2 Scheduling a Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353.4.3 Changing Job Schedules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383.4.4 Stopping a Job from Running . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383.4.5 Specifying Job Recurrence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383.4.6 Running a Job in the Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393.4.7 Other Report Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

4 Working with the Ad Hoc Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414.1 Understanding the Ad Hoc Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

4.1.1 Topics and Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414.1.2 The Ad Hoc Editor Tool Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424.1.3 Tables, Charts, and Crosstabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

4.2 Designing an Ad Hoc Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454.2.1 Selecting the Content of a Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454.2.2 Formatting the Appearance of a Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484.2.3 Viewing and Running a Report in the Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

4.3 Exploring and Analyzing Data in the Ad Hoc Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504.3.1 Creating an Initial Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514.3.2 Focusing on Specific Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524.3.3 Refining the Crosstab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

4.4 Additional Features of the Ad Hoc Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574.4.1 Creating Custom Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574.4.2 Using Input Controls and Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 594.4.3 Switching Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 614.4.4 Sorting Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 624.4.5 Working with Charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634.4.6 Working with Crosstabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

4.5 Creating a Report from a Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 674.5.1 Choosing Ad Hoc Data From a Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 674.5.2 Using the Choose Ad Hoc Data Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 714.5.3 Creating Topics from Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

4.6 Uploading a Topic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 764.7 Configuring System-level Ad Hoc Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

4.7.1 Limits on Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 784.7.2 Data Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

5 Adding Reports Directly to the Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 795.1 Overview of a Report Unit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 805.2 Adding Report Units from JRXML Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

5.2.1 Simple Report Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 805.2.2 Uploading the Main JRXML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 805.2.3 Uploading Suggested File Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 815.2.4 Defining the Data Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 835.2.5 Defining the Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

4

Table of Contents

5.2.6 Validating the New Report Unit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 865.2.7 Complex Report Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 875.2.8 Uploading Undetected File Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 885.2.9 Adding Input Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 905.2.10 Completing the Complex Report Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 995.2.11 More about Datatypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1005.2.12 Localizing JRXML Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1015.2.13 Default Fonts in JasperServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

5.3 Editing JRXML Report Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1025.4 Using the JasperServer Plug-in for iReport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

5.4.1 Connecting to JasperServer from iReport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1035.4.2 Creating a Report Unit in the Repository from iReport . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1055.4.3 Managing Resources in the Repository from iReport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1065.4.4 Editing a Report in the Repository from iReport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1075.4.5 Running a Report from iReport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1085.4.6 Creating Reports in iReport Based on a Domain in JasperServer . . . . . . . . . . . . . . . . . . . 1085.4.7 Creating Chart Themes in iReport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

6 Creating Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1156.1 Introduction to Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

6.1.1 Domain Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1166.1.2 Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1166.1.3 Components of a Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1166.1.4 Sample Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1176.1.5 Overview of Creating a Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

6.2 Example of Creating a Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1176.3 Using the Add New Domain Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

6.3.1 The Data and Design Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1256.3.2 The Resources Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1266.3.3 Domain Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

6.4 Using the Domain Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1276.4.1 Designer Tool Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1276.4.2 Tables Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1276.4.3 Manage Data Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1286.4.4 Derived Tables Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1296.4.5 Joins Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1296.4.6 Calculated Fields Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1306.4.7 Filters Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1316.4.8 Display Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1326.4.9 The Properties Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1336.4.10 Domain Design Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

6.5 Editing a Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1356.5.1 Maintaining Referential Integrity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1366.5.2 Fixing Referential Integrity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

5


7 Advanced Domain Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1397.1 The Domain Design File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

7.1.1 Exporting the Design File from a Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1407.1.2 Working With a Design File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1407.1.3 Structure of the Design File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1417.1.4 Uploading a Design File to a Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

7.2 The DomEL Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1507.2.1 Datatypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1517.2.2 Field References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1517.2.3 Operators and Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1527.2.4 Return Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

7.3 Resources of a Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1537.4 The Domain Security File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

7.4.1 Row-Level Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1577.4.2 Column-Level Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

7.5 Locale Bundles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1617.5.1 Defining the Internationalization Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1627.5.2 Creating Locale Bundle Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

8 Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1658.1 Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

8.1.1 Message List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1658.2 iReport Plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

8.2.1 JasperServer Plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1668.2.2 Domain Plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

6

Introduction to JasperServer

1 INTRODUCTION TO JASPERSERVER

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 integration 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 business intelligence users, Jaspersoft offers JasperAnalysis, which runs on JasperServer. This optional component is described in its own user guide.

While the Ad Hoc Editor lets users create simple reports, more complex reports can be created outside of JasperServer. You can either use iReport (or iReport) or manually write JRXML code to create a report that can be run in JasperServer. Jaspersoft recommends that you use iReport unless you have a thorough understanding of the JasperReports file structure. See 5, “Adding Reports Directly to the Repository,” on page 79 and 8.2, “iReport Plug-ins,” on page 166.

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 chapter contains the following sections:Logging InThe Home PageSearching the Repository

7

http://www.jaspersoft.com/ultimate-guides

http://support.jaspersoft.com/


1.1 Logging InTo protect the data that you can access through JasperServer, all users are required to log in with a password.

To login to JasperServer:1. Enter http://hostname:8080/jasperserver-pro in your web browser (where hostname is the name of the

computer where JasperServer is installed).The Login page appears:

2. Before logging in, you may want to review the links on the login page, such as the link to the Online Help.3. To login, enter your user ID and password.

If you installed the sample data, you can use any of the user names and passwords shown, as well as your own. The default administrator user is jasperadmin and the password is the same; you should change it after installation.

4. If the Organization field appears, enter the ID or alias of your organization. If you don’t know it, contact your administrator.

5. Click Show locale & timezone. The Locale controls appear in the Login pane.

6. Select your locale and time zone from the drop-downs.7. Click Login.

If all information is valid, you are logged in, and JasperServer displays the home page.

1.2 The Home PageThe Home page lets you quickly access the most-used features of JasperServer:

Figure 1-1 JasperServer Login Page

If the Change Password feature has been implemented on your system, you can change your password by clicking Change password. For more information about this configuration option, refer to the JasperServer Administrator Guide.

8


The Home page for standard users has three icons that are linked to the basic functions of JasperServer:view your reports – Displays a list of the reports that you can view and run.create a report – Launches the Ad Hoc Editor in which you can design reports interactively.analyze your results – Displays a list of analysis views. Available only if you implement JasperAnalysis.

The three menus in the menu bar and the links to the Online Help and Log Out link in the upper right appear on all JasperServer pages. The search field is described in section 1.3.1, “Searching by Name,” on page 11. The menus offer these options:

For administrators, the Home page has additional options and menu items for managing user, roles, organizations, and settings. Administrator functions are documented in the JasperServer Administrator Guide.

Figure 1-2 JasperServer Home Page

Menu Description

Home Returns to this Home page.

View Repository – Displays the repository’s folders and the resources they contain, including reports, report output, data sources, images, and other files used in reports. Access to repository folders and objects is always subject to permissions set by administrators.Reports – Displays all the reports in the repository that you can view, run, and edit, depending on permissions. Same as clicking view your reports.Analysis – Displays all the analysis views in the repository that you can view, run, and edit, depending on permissions. Same as analyze your results. Available only with JasperAnalysis.Messages – Displays system messages, such as an error in a scheduled report.

Create Ad Hoc Report – Launches the Ad Hoc Editor in which you can design reports interactively. Same as clicking create a report.Dashboard – Launches the Dashboard Designer in which you can lay out multiple reports and their supporting input controls, labels and images.

9


1.3 Searching the RepositoryThe repository is JasperServer’s internal storage for all reports, dashboards, analysis views and related files. The repository is organized as a tree structure of folders containing resources, much like a file system. However, JasperServer stores all objects and files in a private database that is otherwise inaccessible, except to administrators. This release of JasperServer introduces a search interface for the repository.

To access the repository, select View > Repository from any page of JasperServer.

The repository page is also where search results are displayed, as well as lists of reports and analysis views. As shown in Figure 1-3, the repository page has the following features:

Search controls – Let you find resources by searching for text in their names or descriptions.Folder tree – Lets you restrict search results to branches of the tree, or if Include subfolders is cleared, lets you browse individual folder contents.Filters for refining results – Provide a quick way to find resources based on other criteria such as type or access time.Bulk operation controls – For selecting and copying, cutting (moving), or deleting multiple resources at once.Search expression and sorting – An interactive status bar showing the search criteria, folders, filters, and sorting criteria.List of resources – The resources in the repository that meet the search criteria, grouped by resource type when appropriate. Click or right-click a resource in the list to view it or see what actions are available.

The new repository interface is designed to help you find resources faster by using intuitive search criteria. Instead of viewing resources by folder alone, the repository now provides many other filters such as who modified the resource and when. By clearing the check box to Include subfolders, you can still browse folder by folder, but once you are familiar with the search interface, you can often find resources with fewer clicks.

All of the controls on the repository page make it easy to refine or enlarge your set of results. In addition, JasperServer remembers your settings so that your most commonly needed resources stay visible when you return to the repository page.

The following sections explain how to use the search features of the repository page.

Figure 1-3 Repository Page

10


1.3.1 Searching by NameUse the search field at the top of every JasperServer page to begin a search at any time. Search terms are not case-sensitive. When you click Search, it opens the repository page with the same search term and displays the results.

JasperServer matches the search term, even word fragments, anywhere it appears in the display name or description string of a resource. JasperServer does not match folder names or display folders in the results. If you enter multiple words, JasperServer searches for resources that match all words, but not necessarily in order. Do not enter quotes around terms or any symbols between terms. Figure 1-4 shows the results of a search for the term “account” in the sample data.

If you enter a search term and click Search on the repository page, the search uses the current settings on the page. If you enter a search term and click Search at the top of any other page, the search uses the default settings:

Include subfoldersStart at the top-most folder visible to your userFilter for visualization types onlySort alphabetically by name

To refine the search, select a folder or filter as explained in the following sections. To cancel search by name, click the icon in the search field to clear the search term and update the search results according to the remaining settings.

1.3.2 Navigating the Folder TreeThe folder tree shows the folders in the repository that your user has permission to view. Use the icons to expand the tree and view all nested folders. Click a folder name to select it.

There are two ways to navigate the folder tree:Search – When Include subfolders is checked, selecting a folder searches the entire branch of the tree starting at that folder. This mode is most useful in combination with other search settings, allowing you to search by name or by resource type across the entire repository or a specific branch of it. By default, Include subfolders is checked.Browse – Clear the box next to Include subfolders to restrict the scope of any search to the resources directly contained in the selected folder. This mode mimics a file system browser, letting you explore folder by folder. This mode works best when you clear the search term and select All types so that the results are exactly the contents of the selected folder.

Figure 1-4 Search Field and Search Results

11


1.3.3 Refining With FiltersThe filters below the folder tree let you refine your search using several other resource attributes. For example, these filters can help you find your most recently viewed reports. You can set each filter independently of the others.

The user filter has the following settings:

The resource type filter has the following settings:

The access time filter has the following settings. All times are relative the user’s effective timezone:

The scheduled report filter has the following settings:

Filter Setting Description

Changed by anyone (default)

Does not take into account user access to the resource.

Changed by me Selects only resources that have been last modified by the currently logged in user.

Viewed by me Selects only resources that have been run and viewed by the currently logged in user. This filter not only applies to visualization types, but also to resources that are included in reports such as images.


All types Does not take into account the resource type; as a result, every type is displayed.

Visualization types (default)

The default filter that includes reports, dashboards, and analysis views. These are the resources that can be viewed by anyone who has read access.

Reports Displays only reports, both JRXML reports and Ad Hoc reports.

Report outputs Displays only the output from reports that were scheduled or run in the background. Report output can be any of the supported export types (HTML, PDF, etc).

Dashboards Displays only dashboards.

Analysis views Displays only analysis views (if you implement JasperAnalysis).

Domains Displays only Domains.

Data sources Displays only data sources.

Other types Displays all types except reports, report output, dashboards, views, Domains, and data sources. This includes input controls, data types, images, and other files that only administrators may add to the repository.


Any time (default) Does not take into account the last modification time of a resource.

Today Resources viewed or modified since the previous midnight.

Yesterday Resources viewed or modified during the previous day ending at midnight.

Past week Resources viewed or modified during the past 7 days, including today.

Past month Resources viewed or modified during the past 30 days, including today.


Any schedule (default) Does not take into account the existence of scheduled jobs.

Scheduled Only reports that have scheduled jobs.

12


1.3.4 Changing the Search ExpressionAbove the list of resources, the search expression shows you all of the criteria that contribute to the search. It contains the following elements, always in this order from left to right:

The search term, if any, or the word All.The folder selected, if any.Any and all filter settings.

The search expression provides a quick visual summary of the search criteria for the list of results that appear right below it. The search expression is also interactive, allowing you to easily remove some of the filters. It supports the following actions:

If there is more than one filter, clicking any one of them removes all those to the right of it.If there is a folder selected that is nested more than one level, you can click any parent folder to select it instead.You can click the search term or the word All to remove any and all folders and filters to the right of it.

After any one of these actions, the search controls displayed on the left are refreshed, and the results are updated.

To the right of the search expression, the sort criteria let change the order of the results. The following sorting is supported:Click Name to sort alphabetically (A at the top). This is the default sort order.Click Modified Date to sort by the latest modified time and date (most recent at the top).

1.3.5 Interacting With the List of ResourcesThe list of resources is always the set of results determined by the current search criteria. Because search results can be quite large, the list of resources has two modes:

Multiple Types Condensed – When there are more than two types of resources listed, the number of resources of each type is limited to a certain number, by default 5. When there are more resources of that type, there is a link to see all of that type. You can quickly scroll through the condensed results and find the type of resource you want. Click the See all... link to display the results of that type.Single Type Expanded – When there is a single type of resource in the results, either by circumstance, by clicking a See all... link, or because a single-type filter is selected, all resources are listed, with a scroll bar if necessary. If the list of results is still too long, enter or refine the search term, or select additional filters.

Once the resource or resources you want are displayed, there are several ways to interact with them:Click the name of a report or dashboard to run and view it.Right-click the name of a resource to access other operations on the context menu, for example Open in Designer... Items appear on the context menu according to the permissions granted to your user.Check the box beside the resource name or click anywhere in the row to select it. Check several boxes or Control-click anywhere in the rows to select multiple resources. You can drag and drop selected items to move them or press Control while you drag and drop items to copy them. When you have multiple resources selected, you can also used the bulk operation buttons above the results list: Copy, Cut (move), or Delete. You must have the appropriate permissions on the selected items and the target folder to move, copy, or delete resources.For more information about permissions and repository operations, see the JasperServer Administrator Guide.

Scheduled by me Only reports that have jobs scheduled by the currently logged in user.

Not scheduled Only reports that do not have scheduled jobs, and all other resource types.

To remove the search term, click the icon in the search field. The search expression then displays All.

When you click See all... for a type that has a single-type filter, for example Domains, that filter is automatically applied. The filter display and the search expression refresh to reflect this. Use the search expression to remove the filter if necessary. When no filter exists for that type, for example input controls, the filter display and search expression are not updated. Use the type filter drop-down to change the types displayed.


13


There are two icons that may appear between a report name and its check box:+ indicates that the report has saved options for its input controls. Click the + icon to list the saved options below the report. For more information, see section 3.3, “Running a Report with Input Controls or Filters,” on page 30.

indicates that the report has been scheduled to run or that it is currently running in the background. Click this icon to view the list of jobs scheduled for the report. For more information, see section 3.4, “Scheduling Reports,” on page 34.

14

Working with Dashboards

2 WORKING WITH DASHBOARDS

A dashboard displays several reports in a single, integrated view. A dashboard can also include input controls (that determine the data displayed in one or more frames), other dashboards, and custom frames that point to URLs to any other content. By combining different types of related content, you can create appealing, data-rich dashboards that quickly convey trends.

This chapter contains the following sections:Viewing a DashboardCreating a DashboardEditing a DashboardDesigning Reports for Dashboards

Figure 2-1 Dashboard with Ad Hoc Table, Chart, and Crosstab

15


2.1 Viewing a DashboardYou can view an existing dashboard if you have the proper permissions. By default, the repository includes the /Dashboards folder where dashboards might be saved.

To view a dashboard:1. In the Search field, enter supermart and click Search.

The search results are displayed in the repository.2. Click the name SuperMart Dashboard in the list of results. Alternatively, right-click the name and select View from the

context menu.JasperServer displays the dashboard, which includes three reports. When you mouseover each report, controls appear for that individual report.

3. Click to refresh the report’s content, and click to open the report in a new window. 4. Select new values from the Start Month and End Month drop-downs and click Submit to change the data displayed.

All three reports update to display data for the months you indicate. 5. Click Reset to set the input controls to the last values saved and return the dashboard to its initial view.6. When done, click View > Repository to go back to the repository page.

Keep these points in mind when viewing a dashboard that has input controls:An input control may appear as a text field, a drop-down, a check box, multi-select list box, or a calendar icon.If one of the frames in a dashboard does not refer to an input control, that frame does not update when you change that input control’s value. Only reports that refer to the input control reflect the change. If the dashboard does not include a Submit button, the changes take effect immediately when you change the input control’s value.

If a dashboard includes a Print View button, click it to display the dashboard without JasperServer’s header and footer; depending on your web browser, this also opens your browser’s Print window.

Figure 2-2 SuperMart Dashboard Example

16


2.2 Creating a DashboardAny user can create a dashboard, though a user’s permissions in the repository may limit the content they can add and the location where they can save it.

This section includes:Dashboard OverviewCreating a Simple DashboardAdding Controls to a DashboardAdding a Custom URL to a DashboardRefining a Dashboard’s LayoutTips for Designing DashboardsAbout Screen Sizes

2.2.1 Dashboard OverviewA dashboard can include any of the following:

Reports in the repository.Special content:

Custom URL. Any URL-addressable web content. JasperServer dashboards can point to any web content, so this feature has nearly-limitless possibilities. For example, you might include a frame that points to the logo on your corporate website; when that logo changes, your dashboard will automatically update to reflect the branding change. A more complex example is described in “Creating a Dashboard” on page 17.Free Text. A free-form text entry field. Resizing this type of item changes the size of the font in the label. Use free text items to add titles and instructional text to your dashboard.Controls (Single or Multiple). If a report on the dashboard refers to input controls or filters, you can add them to the dashboard. When you add a control, JasperServer automatically adds a label for it as well. The input control can be mapped to one or more frames. For example, if multiple reports include the same parameter, the corresponding control is automatically mapped to each of those reports when you add the input control to the dashboard. Controls can also be manually mapped to custom URL frames.

Standard controls:Submit. Applies the values in the dashboard’s input controls to the reports that refer to each input control. JasperServer refreshes these reports to display the new set of data. If the dashboard doesn’t include a Submit button, changes to input control values are reflected immediately.Reset. Resets the values of the input controls to the last value selected when the dashboard was saved. Print View. Displays the dashboard without buttons or JasperServer’s header and footer, and (depending on your browser) opens your browser’s Print window.Text Label. A label for an input control. When you add an input control to the dashboard, JasperServer automatically adds a text label for it. Resizing this type of item only changes the size of the label itself; the font size in the label is fixed.

Multiple controls are those used by more than one report. Single controls are those that correspond to parameters included in a single report.

17


2.2.2 Creating a Simple Dashboard

This section walks you through the creation of a dashboard.

To create a simple dashboard:1. Click Create > Dashboard.

The dashboard designer appears, displaying the list of available content and the dashboard area.2. In the Available Content list, navigate to the /Reports/Samples folder, and click the arrow to the left of the Freight report

to move the report to the dashboard area.The report appears in a frame in the upper left corner of the dashboard area. Next to it, JasperServer shows an outline that indicates where the next frame will be added if you click a field’s arrow.

3. In the Available Content list, click the arrow to the left of the Accounts report to move the report to the dashboard area.4. Hover your cursor over the bottom of right-hand edge of the frame containing the Freight report; when your cursor

changes to a resizing icon ( ) click and drag the edge of the frame to resize it. Adjust the width and height of the frame to display the default data returned by the Freight report.

5. Resize the frame containing the Accounts report to fit its width.6. With both frames sized for their reports, the dashboard is wider than the specified screen size. JasperServer indicates this

by displaying a red guide line that appears over the Accounts report.JasperServer allows you to save the dashboard even when its contents hang over the edge of the dashboard area. This is because the dashboard area is meant as a guide: if the content fits in the dashboard area without showing the red guideline, you can be sure that a user with the selected resolution will be able to view the entire dashboard without using the browser’s scroll bars. In fixed sizing mode, if your content hangs over the edge, the user may have to scroll across or down to see the entire dashboard. For more information, see 2.2.7, “About Screen Sizes,” on page 24.

7. Click Preview. The end user view of the dashboard appears; depending on your browser, it may appear in a new tab or a new window.

Figure 2-3 List of Available Content in the Dashboard Designer

To add a report to a dashboard, you must have permission to view the report.

18


8. Return to the designer and click Save.You are prompted for the name and location where the dashboard should be saved. By default, the dashboard is saved in the /Dashboards folder with the name New Dashboard.

9. Accept the default location, and specify the name Freight Dashboard.10. Click Save.

The dashboard is saved to the repository.

2.2.3 Adding Controls to a DashboardSince the Freight report refers to input controls that determine the data it returns, those controls can be added to the dashboard.

To add controls to the dashboard:1. If it isn’t open, locate the Freight Dashboard created in section 2.2.2, typically in the /Dashboards folder.2. Right-click the dashboard name and select Open in Designer... from the context menu.

The Freight Dashboard appears in the designer, as shown in Figure 2-4.3. In the Available Content list, open the Special Content > Single Report Controls folder.

The three input controls associated with the Freight report appear.4. Click the arrow to the left of the Country input control to move the control to the dashboard.

The Country input control and its label appear in the upper-left corner of the dashboard area, nudging the Freight report down to accommodate the new control. If you wanted to place the input control in another location, you could drag it from the Available Content list to the desired location.Note that the input control and label are independent; you can delete one or the other and resize them individually.

5. Select a new value from the Country input control, and notice that the data displayed in the Freight report changes; the Account report does not update because it does not refer to an input control named Country.

6. Use the arrows to add the OrderID and RequestDate controls, as well.7. Click just above and to the left of the Country label, and drag the mouse to draw a selection rectangle. Draw the rectangle

across the three input controls and their labels to select them.8. Click one of the selected input controls, and drag down to move them below the Freight report’s frame.9. Draw a selection rectangle to select the OrderID input control and its label, and drag them directly beneath the Country

input control.

Figure 2-4 Creating a Simple Dashboard with Sample Reports

19


10. Draw a selection rectangle to select the RequestDate input control and its label, and drag them directly beneath the OrderID input control.

11. Click the OrderID label, and select Edit Label form the context menu.The label becomes editable and its text is selected.

12. Type Order and press Return.13. Change the RequestDate label to Date.14. In the Available Content list, navigate to Special Content > Standard Controls, and drag the Submit and Reset buttons

so they are underneath the input controls in the dashboard area.By default, a dashboard automatically updates when you change the values in its input controls. When the dashboard includes the Submit button, JasperServer doesn’t update the dashboard until you click the Submit button.

15. Click Save.


2.2.4 Adding a Custom URL to a DashboardYou can create a frame that displays any URL-addressable content. Such mashups can help you leverage data from many sources in a single, integrated view.

To add a custom URL:1. If it isn’t open, locate the Freight Dashboard saved in section 2.2.3, typically in the /Dashboards folder.2. Right-click the dashboard name and select Open in Designer... from the context menu.

The Freight Dashboard appears in the designer, as shown in Figure 2-4.3. In the Available Content list, select Custom URL (in the Special Content folder), and drag it to the lower-left corner of

the dashboard.You are prompted to enter the URL of the web page you want the frame to display.

4. In the URL field, enter news.google.com.5. Click the check box next to Country to select that input control, and in the URL Parameter Name field, replace the

default text (Country) with the letter q. Note that this field is case-sensitive.This tells JasperServer to map the dashboard’s Country input control to Google’s q (query) parameter. Now, when you select a value in the Country input control, JasperServer passes that value to news.google.com, so that the news displayed in the frame relates to the selected country.Note that the other two input controls also appear in the URL definition window; if news.google.com accepted a parameter that was compatible with these input controls, you could check their check boxes to associate the URL with these input controls, as well.

6. Click OK to close the custom URL dialog.

Figure 2-5 Defining a Custom URL Frame

20


7. Select a new value from the Country input control, click Submit, and notice that the news displayed in the custom URL frame changes.

8. Resize the custom URL frame so that only the first article’s synopsis appears.9. Drag the custom URL frame to the left so that its left edge is aligned with the right edge of the input controls.10. Click the custom URL frame, and click Auto-refresh Interval on the context menu.

The menu expands to display options for how frequently JasperServer should refresh the frame’s content. Smaller values make JasperServer update the frame more often. By default, a frame is never automatically refreshed (that is, its Auto-refresh Interval is set to Manual Only).

11. Click 5 Minutes beneath the Auto-refresh Interval on the context menu.Auto-refresh only affects the end user view of the dashboard. In the designer, the frame is never auto-refreshed.

12. Click Save.


2.2.5 Refining a Dashboard’s LayoutOnce your overall layout is complete, you can refine the look and feel of your dashboard.

To refine the dashboard’s layout:1. If it isn’t open, locate the Freight Dashboard saved in section 2.2.4, typically in the /Dashboards folder.2. Right-click the dashboard name and select Open in Designer... from the context menu.

The Freight Dashboard appears in the designer, as shown in Figure 2-4. Note the gap at the top left when you moved the input controls to a new location, as described in 2.2.4, “Adding a Custom URL to a Dashboard,” on page 20.

3. Click in the upper-left corner and draw a selection rectangle around all the frames, click one of the selected frames, and drag up to reduce the unused space at the top of the dashboard.

4. Click Preview.The end user’s view of the dashboard appears; if the dashboard is already open in your browser, JasperServer updates that page rather than opening a new window or tab.

5. In the Country field, select a new value. Note that the Freight report and custom URL frames do not update; this is because the dashboard includes the Submit button.

6. Return to the dashboard designer and, in the dashboard area, hover your cursor over the Submit button, and when the hover border appears, click it.

7. From the context menu, click Delete Item.The Submit button disappears.

8. Reposition the Reset button to so it’s centered in the available space.9. Click in the Dashboard Selector, and select Add Title Text in the context menu.

The title becomes editable.10. Enter Orders and Current Events by Country.11. Click Preview.

The end user view of the dashboard appears.12. Change the value in the Country input control, and note that the dashboard reflects the change immediately.13. Return to the dashboard designer and click Save.


21


2.2.6 Tips for Designing DashboardsWhen you are creating or editing a dashboard, keep these tips in mind:

You can drag items from the Available Content list and drop them to add them to the dashboard, or use the Available Content context menu Add to Dashboard option. Press the Ctrl key while dragging or resizing items and frames for smoother cursor movement. This disables the default snap-to-grid behavior.Use Ctrl-click to select multiple frames and items in the dashboard area.

Click to hide the Available Content list; display the list again by clicking .Use the Hide Scroll Bars option on the frame context menu when you can size the frame to exactly match its content. This is especially helpful for charts and small crosstabs.The context menu changes depending on your selection. For example, it might include the Delete Item or Delete Frame option, depending on whether you selected a button or a frame. If you select multiple items or frames, the context menu only includes options that apply to all the selected items. For example, if you select a frame and a button, the context menu only includes the Delete Items option; when you select multiple frames, the context menu includes several options that can apply to frames, such as Hide All Scroll Bars and Auto-refresh Interval.You can use the arrow keys to move selected content one grid space at a time. Press the Ctrl key to move the selected content a single pixel at a time.You can’t resize buttons or input controls.When you delete a report with input controls from the dashboard, the controls are also deleted, but their labels remain. Delete them manually. If a custom URL frame is mapped to one of the input controls that was deleted, JasperServer shows the default URL without passing the parameter.Drag an item from the Available Content list and drop it on an existing frame to replace the existing content.To create a new version of a dashboard, open it in the designer and click Save As on the Dashboard Selector context menu.A dashboard can include other dashboards, so long as this doesn’t create a circular dependency. Put another way, you can’t add a dashboard to itself.

Figure 2-6 Dashboard with Sample Reports and Special Content

22


If a report displayed in a dashboard is moved to a new location in the repository or if it is deleted entirely, it is deleted from the dashboard.Select multiple frames to change their sizes all at once. When you drag the edge of one frame, the other frames change size as well.The dashboard designer may seem unwieldy if you design for a screen size as big as or larger than your own; in particular, horizontal scrolling can be awkward. Try hiding the content pane, or using a larger monitor. You can also design the dashboard for your resolution, and then select Use Proportional Sizing from the Dashboard Selector context menu. For more information, see 2.2.7, “About Screen Sizes,” on page 24.Not all web pages support the technology underlying JasperServer’s dashboards (IFrame). In such cases, the URL frame’s behavior may be inconsistent.By default, JasperServer assumes that you want to use the HTTP protocol for custom URL frames. However, you can specify that it use the FILE protocol by entering file:// at the beginning of the value in the URL. In this case, JasperServer uses the FILE protocol, and looks for the file you specify in the JasperServer’s WEB-INF directory. This is helpful for including images.If you have multiple reports that refer to the same input control, but you do not want them to be controlled by a single input control, create two dashboards that each refer to the input control; then create a dashboard that includes those dashboards. Now, users can set the input controls separately for each set of reports.Adding the same dashboard twice to a parent dashboard can create a compelling comparison.

Figure 2-7 A Dashboard Comparing Data from Two Countries

23


2.2.7 About Screen SizesWhen you create a dashboard, you can set the screen size to change the dashboard area to match a particular screen resolution. For example, if you are designing a report for end users who use laptops that only display a screen resolution of 800 by 600 pixels, you can set the dashboard area to 800 by 600 pixels to emulate your end users’ screen size.

By default, the dashboard designer supports five standard screen resolutions, which are available under the Screen Size option in the Dashboard Selector context menu. When a dashboard uses fixed sizing, its frames do not resize automatically when the window size changes.

In addition to fixed screen resolutions, dashboards support proportional sizing, which calculates frame sizes using percentages of the total window size, rather than using fixed values. Put another way, when a dashboard uses proportional sizing, its frames resize relative to the size of the browser window. Note that frames do not resize automatically in the designer; proportional sizing is only evident in the end user’s view of the dashboard, or when you select a new screen size in the designer.

If a dashboard that uses proportional sizing is bigger than the specified screen size, when the dashboard is viewed, Jaspersoft resizes the frames so that they all appear in the window without requiring the user to use the browser’s scroll bars. This may result in a change to the shape of the frames.

In proportional sizing, note that:You can resize free text items to a smaller size, but you can’t make them bigger.The grid turns red when any content hangs over the edge of the dashboard area.

2.3 Editing a DashboardYou can edit a dashboard if you have the proper permissions.

To edit a dashboard:1. Select View > Repository and search or browse for the Dashboard you want to modify.

By default, the repository includes the /Dashboards folder where you can store your dashboards. 2. Right-click the dashboard and select Open in Designer... from the context menu.

The designer appears, displaying the dashboard.3. Edit the dashboard by adding, removing, resizing, or dragging content.

For more information about working with dashboard content, see section 2.2, “Creating a Dashboard,” on page 17.4. When you are satisfied with the dashboard, click Save.5. To create a new version of the dashboard, select Save As from the Dashboard Selector context menu, and specify a new

name.

2.4 Designing Reports for DashboardsWhen defining reports for a dashboard, keep these hints in mind:

Charts and small crosstabs are best suited to dashboards. However, you can design table reports that work well in the dashboard. Such reports tend to be very narrow and typically refer to input controls to limit the number of rows they return.The reports should be small, since dashboards typically contain multiple reports. In particular, your reports shouldn’t be too wide, as horizontal room is always at a premium in a dashboard.When an Ad Hoc report is displayed on a dashboard, its margins are stripped; you don’t need to strip the margins manually when designing the report.

Jaspersoft recommends that you design dashboards using fixed sizing mode, then, switch to proportional sizing before you save.

24


If you want a single input control on the dashboard to control the data displayed in multiple reports, the reports themselves need parameters with the same name as the input control. For example, you might have a query-based list of employee names that can be used in both sales reports and human resources report. When defining a parameter in a report, give it a meaningful name that can be reused in other reports. Then, when two reports that include this parameter are added to the dashboard, their input controls appear as Special Content in the Available Content list. Storing such input controls in the repository encourages their reuse when reports are designed and added to the repository.If a report’s input control is set to display as a radio button set, it is instead displayed as drop-down. If you want to pass a value to an external URL, the URL Parameter Name you specify for the input control must match the name of a parameter that URL can accept. In addition, the value of the input control must also be a value the URL can accept. Beyond these requirements, the target URL is likely to have requirements and limitations. For example, the name of the parameter may be case-sensitive; in this case, the value you enter in the URL Parameter Name field is also case-sensitive. Note that this is the case for Google’s q parameter that is referenced in 2.2.4, “Adding a Custom URL to a Dashboard,” on page 20.It is essential that the input control pass data that the URL can accept. Otherwise, JasperServer may be unable to retrieve the correct data from the external URL.

25


26

Running Reports

3 RUNNING REPORTS

JasperServer makes it easy to run reports that help you understand and present your data to their best effect.

This chapter contains the following sections:Running a Simple ReportRunning a Flash ChartRunning a Report with Input Controls or FiltersScheduling Reports

3.1 Running a Simple ReportSome reports are simple tables with rows and columns of data, as in this report that simply lists accounts.

To run a report:1. On the Home page, click view your reports.

The Repository page appears with a filter showing all reports that your user account has permission to view. This means you can view other users’ reports, so long as you have proper permissions.

The tutorials in this section and throughout the user guide assume that you have installed the sample data that is provided with JasperServer.

If you know the name of the report you want to run, you can enter its name in the Search field and click Search to locate it in the repository. You can also search on partial names or for words in the report’s description. For more information, refer to section 1.3, “Searching the Repository,” on page 10.

27


Use the scroll bar at the right of the page to view the entire list of reports.2. Click the name Accounts Report to run the report. Alternatively, right-click anywhere in the report row and select View

from the context menu. JasperServer displays a message indicating that it is retrieving the data. If necessary, you can click Cancel to stop the report from running. The report appears, containing accounts and contact information. Use the arrows at the top of the page to view the whole report.

3. To view and save the report in other formats, click an export icon: .The output can be exported to a file in these formats: Adobe Acrobat (PDF), Microsoft Excel (XLS, XSLX, or CSV), Microsoft Word (DOCX or RTF), Adobe Flash (SWF), OpenDocument Text (ODT), and OpenDocument Spreadsheet (ODS). You can view the file in its application and save it.

4. To return to the reports listing, click the Back icon .

Figure 3-1 Viewing All Reports in the Repository

Figure 3-2 Output of the Accounts Report

28

Running Reports

3.2 Running a Flash ChartThis release of JasperServer supports Flash charting, a new feature implemented in JasperReports Pro. JasperServer Professional and Enterprise editions include the Maps Pro, Charts Pro, and Widgets Pro component libraries that create visually appealing, animated, and interactive reports:

Maps Pro – Color-coded maps covering all countries and regions of the globe.Charts Pro – Standard and stacked charts with animation and interactivity.Widgets Pro – Non-standard charts such as gauges, funnels, spark lines, and Gantt charts.

These components are based on Fusion libraries and generate Flash output that is embedded in the HTML and PDF output. When a report containing a Maps, Charts, or Widgets Pro element is exported in a format other than HTML or PDF, the space used by the element remains blank.

Flash charts are JRXML reports that are created in iReport Pro and uploaded to the repository as a report unit. JasperServer cannot create Flash charts. For information about creating flash charts, see the iReport Ultimate Guide. To upload JRXML reports, see chapter 5, “Adding Reports Directly to the Repository,” on page 79.

The sample data installed with JasperServer includes a very simple example of each Flash chart:1. From any page in JasperServer, type flash into the search field, and press Enter or click Search.

The repository displays the search results, including Flash Chart Report, Flash Map Report, and Flash Widget Report.2. Make sure Flash is enabled in your browser, then click any of these report names.

The reports launch in the same manner as any other reports. However, Flash charts can be animated as they are drawn, giving them greater visual appeal. Flash charts are also interactive, as explained in the following examples:

The color-shaded states correspond to value ranges given by the legend. To interact with the map in JasperServer, mouse-over any of the states on the map to see the full state name and, when data exists, the value for that state.

To view Maps, Charts, and Widgets Pro elements in JasperServer, Flash must be installed and enabled on your browser. To view these elements in PDF output, you must use a Flash-enabled PDF viewer such as Adobe Reader 9.

Figure 3-3 Output of the Sample Flash Map Report

29


To interact with the pyramid widget in JasperServer, click a segment to separate it from the others. These are simple examples with unrealistic data, but they show how Maps, Charts, or Widgets Pro components can present several layers of information in compelling ways.

Flash charts have many features that are not illustrated in these sample reports, among them:As with any JRXML report, text appearing in the report can be localized, even map labels. For more information about uploading resource bundles for Maps, Charts, or Widgets Pro components, see the iReport Ultimate Guide.Chart elements, map regions, and widget segments are clickable and can be linked to more detailed reports. Depending on the security settings in your Flash player, you may need to enable links in order for them to work.

3.3 Running a Report with Input Controls or FiltersInput controls and enable you to select the data returned when you run the report. When filters are defined in Domain Topics to be prompted, they are rendered as input controls when running the reports based on the Domain Topics.

3.3.1 Simple Input ControlsThe Freight Report example has three input controls: Country, Request Date, and Order ID. When you view the report at first, the report runs with default values. You can then display the controls and run the report with new values.

To run a report with simple input controls:1. In the Search field, enter freight and click Search.

The search results are displayed in the repository.2. Click the name Freight Report in the list of results.

The report appears.

Figure 3-4 Output of the Sample Flash Widget Report

The Open Flash Charts Report listed in the search results is an experimental report that uses a different Flash library. The Maps Pro, Charts Pro, and Widgets Pro components are fully supported by Jaspersoft.

30

Running Reports

In the report as it was saved, the country is Mexico, and so the postal codes and customer IDs are for Mexico. All order IDs are above 10600 and all order dates are after June 1, 1997.

3. To run the report with other values, click the Report Options icon .The Report Options dialog appears.

4. Select USA in the Country field, and click OK.

The report appears with USA as the country instead of Mexico, and the postal codes and customer IDs are for the US.

You can also click Apply in the Report Options dialog to refresh the report but keep the dialog open. This allows you to interact with the report and easily find the data you need.

Figure 3-5 Shipping Report with Country = Mexico by Default

Figure 3-6 Setting Country = USA in the Report Options Dialog

Figure 3-7 Shipping Report With Country = USA

31


5. To make USA the default country, click to display the Report Options page again, then click Save Values.You are prompted to name the new set of default values.

6. In the window, enter USA as the new name, and click OK.

The Report Options dialog now has a drop-down list showing USA as a set of saved values.

If you click Reset, the values of the report options revert back to the original values stored in the report, in this case Mexico.

7. Click the Back icon to display the search page.8. Click the + icon next to the Freight Report to display all saved versions of the report. The new USA version of the sample

report is listed beneath the report’s original version.

9. You can open the report directly with the saved values for the input controls by clicking on the name of the saved version.10. You can add a description to the saved version of the report. Right-click the saved version and select Properties... from

the context menu.

Figure 3-8 Naming the Saved Values

Figure 3-9 Report Options With a List of Saved Values

Figure 3-10 Report With Saved Values in the List of Reports

32

Running Reports

The Resource Properties dialog appears.

11. Enter a description and click OK.The new description will appear in the repository.

3.3.2 Cascading Input ControlsWith simple input controls, every value chosen is independent of the others. Reports can also be designed with cascading input controls, where the choice for one input determines the choices for the other input. For example, the choice of a country determines which states or regions are available to choose from. For more information, see 5.2.9.7, “About Cascading Input Controls,” on page 98.

The following example also demonstrates required inputs, in which case you must enter values before running the report.

To run a report with cascading input controls:1. In the Search field, enter cascading and click Search.

The search results are displayed in the repository.2. Click the name Cascading multi select example report in the list of results.

Instead of running the report, you are prompted to enter new values for them.

3. Select a different country in the first field, in this example, Mexico.The other fields are automatically updated to reflect the state and names associated with Mexico in your data. Cascading input controls are implemented as queries that access your database to retrieve the new values. JasperServer displays an activity monitor while the query is running, and in the case of long queries, you can click Cancel and select different values.

4. Select a different state, for example Guerrero.

Figure 3-11 Adding a Description to a Saved Version of a Report

Figure 3-12 Adding a Description to a Saved Version of a Report

33


The names field updates to reflect the choice of state. The country and state inputs are defined as multi-select; use control-click to select multiple values in each lists. The other values are updated to reflect your choices.

5. Click OK to run the report with your chosen values.The report creates a list of all account names in the chosen states of the chosen countries. The chosen name is listed at the top of the report.

3.4 Scheduling ReportsThe report scheduler enables you to run reports at prescribed times. Jobs that you define in the scheduler run the reports in the background and save the output in the repository. You can view the output there. You can also have the output sent to you and others as email attachments. Any number of jobs can be scheduled for the same report.

Scheduled reports run as the user who defines the job (see 3.4.2, “Scheduling a Report,” on page 35). If the report’s data source is subject to access permissions, the report contains the data that the user has permission to see. For example, Gloria has access only to inventory data from the Southeast US region. Reports that she schedules only show data from that region even when the report is viewed by users in other regions. To see the data for their own regions, the other users need to schedule the report themselves.

Be careful when you schedule a job as an administrative user with no data restrictions. The report will contain all requested data in the data source, and any user that receives the report can view all the data regardless of the user’s access restrictions.

Standard data sources in the repository are not subject to access permissions, but Domains are (see 7.4, “The Domain Security File,” on page 155). External data sources might be subject, as well as data sources authenticated by security frameworks other than the Acegi framework used by JasperServer (see the JasperServer Administrator Guide). In these latter cases, JasperServer returns whatever data is passed to it from the data source. Some data sources can pass access grants along with their data, some cannot. It is up to the user to configure whatever is passed to JasperServer.

Permission to edit a schedule is simpler. Only the user who created the schedule or a user with the administrator role can change or delete it.

3.4.1 Viewing Scheduled JobsTo view the jobs that are currently scheduled for a report, locate the report in the repository; your options vary depending on whether the report has scheduled jobs:

In the repository, reports with scheduled jobs have a small icon beside the report name. Click the icon to see the jobs scheduled for the report. If a report does not have the schedule icon, right-click it and select Schedule... from the context menu.

The scheduled jobs page appears for the chosen report.

Standard users see only the jobs that they have defined themselves; administrators see the jobs defined by all users. In the figure above, Joe User has scheduled three jobs for the Freight Report. The list shows the following information for each job:

ID – The internal ID number of the job, accompanied by a link to edit the job details.Label – A short description provided when creating the job.Owner – The user who created the job.

Figure 3-13 Jobs Scheduled Page for a Sample Report

34

Running Reports

State:Normal – The job is scheduled.Running – The job is currently running.Complete – The job is complete.Error – The scheduler encountered an error while scheduling or triggering the job. This does not include cases where the job is successfully triggered, but an error occurs while it runs.

Last ran at – The last time the report was run.Next run time – The next time the report will run.Checkbox – Select for removal.

Buttons on the page include:

3.4.2 Scheduling a Report

To schedule a report:1. On the Home page, click view your reports; or from any page, click View > Reports.2. Use the search field or browse the list of reports to find the report you want to schedule.3. Right-click the report and select Schedule... from the context menu. If the report already has a schedule that you want to

add, modify, or delete, click the small icon beside the report name.The Scheduled Jobs page appears, as shown in Figure 3-13 on page 34.

4. Click Schedule Job.The Job Details page appears.

5. In the Label field, enter a name for the job. The description is optional.6. Click Next.

Button Description

Back Returns the user to the repository manager or the list of reports.

Schedule Job Opens the Job Details page to define a new job.

Run Now Runs the report in the background, allowing you to continue working in JasperServer. See section 3.4.6, “Running a Job in the Background,” on page 39.

Refresh Refreshes the list of jobs, for example to see if a job has finished running.

Remove Deletes all the jobs selected with a check mark. When a job is deleted while it runs, the report is completed before the job is deleted. JasperServer deletes completed jobs automatically.

Figure 3-14 Job Page for Scheduling a Report

35


The Schedule page appears.

7. Set the following schedule attributes:Time Zone – Specify the time zone in which you wish to define the schedule. The default time zone is the that of the server, or if specified, the time zone you entered at log in. If you are in a different time zone, set this field accordingly so that the report is scheduled at the exact time you intend.Start – Immediately or in the future. Click the calendar icon to select a future start date and time. If you do not specify recurrence below, the start date and time define when the report will run. If you specify recurrence, you may still want to delay the first report date, for example a weekday report that you want to start next week.Recurrence – Choose one of the following:

No Recurrence – Run the report once.Simple Recurrence – Schedule the job to recur at an hourly, daily, or weekly interval.Calendar Recurrence – Schedule the job to recur on days of the week or days of the month.

In this example, the new job will start on a fixed date and run only once. If you select Simple or Calendar Recurrence, additional controls appear on the page. For details, see section 3.4.5, “Specifying Job Recurrence,” on page 38.

8. Click Next.If the report you are scheduling has input controls that prompt for user input, the Parameter page appears.

This dialog is identical to the Report Options dialog. If you have saved values, they appear in a drop-down list at the top. The fields that appear are the input controls defined for the report you are scheduling. You can always set the input values directly, as well as save them as a named set of values.

9. Choose a set of saved values, or set the input controls as desired. In this example, we used the saved values for USA.10. Click Next.

Figure 3-15 Schedule Page for a New Job

Figure 3-16 Parameters Page for Scheduling a Report

36

Running Reports

The Output page appears.

11. On the Output Details page, specify these attributes as needed:Base output file name – The name of the file as it appears in the repository, not including the file extension. The timestamp pattern can be added to the base name, and the format extension is added automatically.Output description – The output file is stored in a repository object, and this is the optional description for the object.Output formats – Select at least one. When you select more than one, each format will be stored as a separate file in the repository and attached as a separate file to the email notification.Locale – Locale for generating the report. The report must support locales, for example a report based on a Domain with language bundles (see section 7.3, “Resources of a Domain,” on page 153).Folder – Select the folder where the report output will be saved. This field is required and you must have write permission to the folder. If you email the report and do not wish to save it, specify the Temp folder.Sequential file names – Appends a timestamp to the names of files created by the job. Useful for the output of recurring jobs or for time-sensitive reports where the output must be dated. When the timestamp is used, the output filename is <basename>-<timstamp>.<extension>.Timestamp pattern – Specify an optional pattern for the timestamp, based on the java.text.SimpleDateFormat. However, valid patterns for report output files can only contain letters, numbers, dashes, underscores and periods. The default pattern is yyyyMMddHHmm, for example 200906150601.For more information on the valid patterns for this field, refer to:http://java.sun.com/j2se/1.4.2/docs/api/java/text/SimpleDateFormat.htmlOverwrite files – If you do not have sequential filenames or if you specify a timestamp pattern that may lead to identical filenames, choose whether newer files overwrite the older ones. To – For email notification, enter one or more email addresses separated by commas.By default, no mail server is configured in a JasperServer installation. To send notifications, your administrator must configure one, as described in the JasperServer Administrator Guide.Subject – Subject line of the notification email.Message Text – Content of the notification email. Attach Files – Select this option to send the output of the report with the email. Be careful when sending reports containing sensitive data via email.Skip Empty Reports – In case of an error and the report is empty, select this option to avoid attaching the empty files.

Figure 3-17 Output Page for Scheduling a Report

37


12. Click Save.The job appears in the list of scheduled jobs (see 3.4.1, “Viewing Scheduled Jobs,” on page 34).

13. In the list of jobs, verify that the next run time for the new job is the date and time you want.

3.4.3 Changing Job SchedulesWhen the start date for a job is in the past, you should create a new job rather than changing the past one.

To edit a scheduled job:1. Open the Jobs List page for the report, as described in section 3.4.1, “Viewing Scheduled Jobs,” on page 34.2. Click edit in the row of the job you want to change.3. Make your changes on the Job Details, Schedule, Parameters, and Output pages of the dialog.4. Click Save. Your update applies immediately.5. In the list of jobs, verify that the next run time for the job is the new date and time you want.

3.4.4 Stopping a Job from RunningTo stop a job from running, delete it.

To delete a scheduled job:1. Open the Jobs List page for the report, as described in section 3.4.1, “Viewing Scheduled Jobs,” on page 34.2. Select the check box in the row of the job you want to delete and click Remove.

3.4.5 Specifying Job RecurrenceSimple recurrence and calendar recurrence allow you run reports automatically on a regular basis. For each, you specify when the job starts, how often it repeats, and when it ends.

Simple recurrence makes the job repeat at an hourly, daily, or weekly interval that is quick to set up.

Simple recurrence supports these options: Start – With simple recurrence, the start date and time determines the date and time of all occurrences, according to the chosen interval. For example, if you want to run the job every Monday, set the start date to the first Monday.Occur – Determines how many times or for how long the job will repeat.

Indefinitely – Runs until you delete the job.Until – Runs until a calendar date is reached. Click the calendar to select the date.X times – Runs the specified number of times.

Every – The interval between jobs, in minutes, hours, days, or weeks.

Figure 3-18 Schedule Page With Simple Recurrence

38

Running Reports

Calendar recurrence enables you to define a job’s recurrence at a higher level of detail, including the time of day, days of the week or days of the month, and months of the year.

Calendar recurrence supports these options: End date – Calendar recurrence runs until a calendar date is reached. Click the calendar to select the date.Minute and Hour – Set the time of day when the job should run. The hours use 24-hour format.You can also enter multiple minutes or hours, as well as ranges, separated by commas. For example, 0, 15, 30, 45 for the minutes and 9-17 for the hours will run the report every 15 minutes from 9:00 a.m. to 5:45 p.m. Enter an asterisk (*) to run the job every minute or every hour. Days – Choose the days when the report should run:

Every Day.Week Days – Choose the days of the week.Month Days – Enter dates or date ranges separated by commas, for example: 1, 15

Months – Choose the months during which the report will run.

3.4.6 Running a Job in the BackgroundRunning a job in the background lets you generate a report, potentially a long-running one, and keep working in JasperServer. It also has the option to export the report directly to any format and save it in the repository. You can also send the generated report by email, which is quick way to share a report with others.

Running a job in the background is equivalent to scheduling the report to run immediately without recurrence.

To run a job in the background:1. On the Home page, click view your reports; or from any page, click View > Reports.2. Use the search field or browse the list of reports to find the report you want to run.3. Right-click the report and select Run in Background... from the context menu.

Figure 3-19 Schedule Page With Calendar Recurrence

If your servers recognize Daylight Savings Time (DST), jobs scheduled using simple recurrence may seem to occur one our later (when DST ends) or one hour earlier (when DST begins). If you want your jobs to recur at the same time of day and respect DST adjustments, use calendar recurrence.

39


4. If the report you are running has input controls or filters that prompt for user input, the Parameter page appears, as in Figure 3-16, “Parameters Page for Scheduling a Report,” on page 36. Choose a set of saved values, or set the fields one at a time.

5. Click Next.The Output page appears as in Figure 3-17, “Output Page for Scheduling a Report,” on page 37. Enter the information as described in step 11 in 3.4.2, “Scheduling a Report,” on page 35.

6. Click Save.The report begins to run immediately and, when finished, stores or sends the output as directed on the Output page. In the meantime, you can continue working in JasperServer.

3.4.7 Other Report ParametersWhen the report scheduler runs a report, a built-in parameter named _ScheduledTime can pass the date and time the report was scheduled to the report. You can use this parameter in a report by declaring it in the JRXML using this syntax:

<parameter name="_ScheduledTime" class="java.util.Date"/>

Use the _ScheduledTime value to display the date the report was run.

40

Working with the Ad Hoc Editor

4 WORKING WITH THE AD HOC EDITOR

The Ad Hoc Editor creates tables, crosstabs, and charts as you drag and drop elements. You can select report types, add fields, define groups, select labels and styles, and select summaries and data formats for each field. You can also use the editor to explore and analyze your data interactively. The Ad Hoc Editor loads data from Topics or Domains, which are repository objects defined by data analysts or server administrators to provide a prepared view of a data source. While Topics contain the fields used directly in a report, Domains give JasperServer administrators and business analysts flexibility to filter the data and create input controls and control the list of available fields.

This chapter contains the following sections:Understanding the Ad Hoc EditorDesigning an Ad Hoc ReportExploring and Analyzing Data in the Ad Hoc EditorAdditional Features of the Ad Hoc EditorCreating a Report from a DomainUploading a TopicConfiguring System-level Ad Hoc Options

4.1 Understanding the Ad Hoc Editor

4.1.1 Topics and DomainsGenerally, administrators and iReport users create Topics as JRXML files. A Topic can also be created from a Domain. For more information, refer to 4.6, “Uploading a Topic,” on page 76 and 4.5.3.2, “Saving Domain Settings as a Topic,” on page 74.

Depending on your configuration, JasperServer may load a Topic or Domain’s entire result set into memory when you edit or run the report. If the data policies are disabled, ensure that each Topic or Domain’s query returns a manageable amount of data, given your environment’s load capacity. Alternately, you can change the data loading policy. For more information, refer to section 4.7.2, “Data Policies,” on page 78.You can edit reports in the Ad Hoc Editor if they were created there originally, but you can’t edit reports in the editor if they originated in iReport.

41


4.1.2 The Ad Hoc Editor Tool BarThe tool bar at the top of the editor provides access to many of the Ad Hoc Editor’s functions:.

Table 4-1 Ad Hoc Editor Tool Bar Icons

Icon Name Description

Presentation Mode

Click this icon to hide the editor interface and view the report by itself. This mode provides a subset of the Ad Hoc Editor’s full feature set. For example, you can change summaries and datatypes for all report types; you can change the chart type, legends, and display options in charts, you can define sorting and the order and size of columns for tables. If the report includes filters created in the editor, those filters can be changed or removed.

Save Place your cursor over this icon to open a menu of save options. Save the report with the current name and location or save it with a new name and location using the Save Report As option.

Run Click this icon to run the report and view its HTML preview. This view opens in a new window or tab, and provides export options to formats such as XLS and PDF. When you run a report, you can change its filter and input control values but you can’t change its layout.

Undo Click this icon to undo the most recent action. For example, if you added a field to a table,

clicking this icon removes the field from the report area.

Redo Click this icon to redo the most recently undone action. This icon is only available immediately after you have clicked the Undo icon; taking any other access disables the Redo icon.

Undo All Click this button to revert the report to its state when you last saved. After you click Undo All, you can click the redo icon to recreate the steps you took before you clicked the Undo All icon.

Sample Mode When working with a table or crosstab, click this icon to load the full set of data. By default, JasperServer only loads a subset of the data in your data source, which improves performance when adding fields, changing grouping, and other changes that require JasperServer to process your data. The words Sample Data appear to the right of the Crosstab tab when you are working with a subset of the data. To work with the complete data set, click this icon. The full data set gives you an accurate view of the your report and is helpful for exploring the data itself. In tables, the subset is helpful in visualizing how your groups will look and for setting summaries, since the summary context menu appears at the bottom of the column.

Pivot or Switch Group

Click this icon to change the way groups are displayed. Depending on the tab you’re viewing, the behavior differs:

Crosstab: pivots the column groups with the row groups. Table: displays the alternate grouping.Chart: displays the alternate grouping.

For more information, refer to 4.4.3, “Switching Groups,” on page 61.

Sort When working with tables, click this icon to view the current sorting (if any) and to select fields by which to sort your data. For more information, refer to 4.4.4, “Sorting Tables,” on page 62.

Input Controls Click this icon to view the input controls applied to this report. In some cases, you can select new values to change the data displayed in the report; for example, you could change the dates the report includes. This icon is only available when input controls are defined for a JRXML-based Topic. For more information, refer to 4.4.2.1, “Using Input Controls,” on page 59.

Styles Click this icon to select a style that determines the fonts and colors in your report. Note that you can’t undo a style selection. Instead, click the Styles icon and choose a different style.

42


4.1.3 Tables, Charts, and CrosstabsThe Ad Hoc Editor provides three modes for working with your data—tables, charts, and crosstabs:

Table – Use tables to view all the data in the report or to summarize the data across one set of related fields. Columns can include both properties and measures; each row represents a something being measured. Rows can be grouped by their properties. For instance, in a report on orders, each column might contain one measurement of the orders, and the rows could be grouped by city and product.

Page Properties

Place your cursor over this icon to open a menu of page-level options. You can:Change whether to display the filter pane.Change whether to display the title.Change the page orientation.Change the page size.

In tables, you can also hide or show the detail rows when the data is summarized. This option is only available if the table includes grouped columns.

Date Placed Date Filled Payment ReceivedCity A

Product 01Date Date AmountDate Date AmountDate Date AmountDate Date AmountDate Date Amount

Product 01 totals: Count SumProduct 02

Date Date AmountDate Date AmountDate Date AmountDate Date AmountDate Date AmountDate Date Amount

Product 02 totals: Count Count SumProduct 03

Date Date AmountDate Date AmountDate Date AmountDate Date Amount

Product 03 totals: Count SumCity A totals: Count SumCity B

Product 01Date Date AmountDate Date AmountDate Date AmountDate Date AmountDate Date Amount

... ... ...

Table 4-1 Ad Hoc Editor Tool Bar Icons

Icon Name Description

43


Chart – Use charts to compare one or more measures across multiple sets of related fields. Charts summarize data in a graphical representation that can highlight your successes and challenges. With the exception of time series and scatter charts, each type of chart compares summarized values for a group. For example, you could click the Chart tab to view the data in a bar chart that showed the sum of payment received for each of the products in each of the cities.

Depending on your needs, you could configure the chart in a number of ways: you could group the bars by region or city, or use a completely different chart type, such as a pie chart in which each slice depicts the payment received grouped by product or city.Crosstab – Use crosstabs to summarize data across multiple sets of related fields. Crosstabs are more compact representations than tables. Columns and rows specify properties that are used as dimensions for grouping; cells contain the summarized measurements. For instance, the example above could be displayed in a crosstab with columns grouped by sales managers and year, rows grouped by city and product, and two data measurements in each cell.

Total Payments Received

City A City B City C

Product 01 Product 02 Product 03

Tom Harriet Manager Totals

2007 2008 Year Totals 2007 2008 Year Totals

City A Product 01 FilledPayment

FilledPayment

FilledPayment

FilledPayment

FilledPayment

FilledPayment

FilledPayment

Product 02 FilledPayment

FilledPayment

FilledPayment

FilledPayment

FilledPayment

FilledPayment

FilledPayment

Product 03 FilledPayment

FilledPayment

FilledPayment

FilledPayment

FilledPayment

FilledPayment

FilledPayment

Product Totals

FilledPayment

FilledPayment

FilledPayment

FilledPayment

FilledPayment

FilledPayment

FilledPayment

City B Product 01 FilledPayment

FilledPayment

FilledPayment

FilledPayment

FilledPayment

FilledPayment

FilledPayment

... ... ... ... ... ... ... ...

City Totals FilledPayment

FilledPayment

FilledPayment

FilledPayment

FilledPayment

FilledPayment

FilledPayment

44


4.2 Designing an Ad Hoc ReportWhile many users think of the Ad hoc Editor as a report designer. This section discusses some of the editor’s basic functionality, including:

Selecting the Content of a ReportFormatting the Appearance of a TableViewing and Running a Report in the Editor

4.2.1 Selecting the Content of a ReportIn the following example, you’ll create a table that shows the ship date and shipping charge of orders; this table might be used to analyze whether shipments could be combined to save on costs.

To design a table in the Ad Hoc Editor:1. After logging into JasperServer, click Create > Ad Hoc Report.

The Topics and Domains window appears.

2. On the Topics tab, select the demo for adhoc Topic, click Table, and click Open Report.The location of this Topic may depend on your system configuration. It is typically in Ad Hoc Components/Topics.The Ad Hoc Editor appears. The fundamental areas in the editor are:

The tool bar.The Domain or Topic and its list of available fields.The report type tabs (Chart, Table, and Crosstab).

The Ad hoc Editor is also helpful in exploring and analyzing your data; for more information, see 4.3, “Exploring and Analyzing Data in the Ad Hoc Editor,” on page 50.

While the example in this section is based on a JRXML Topic, the concepts and procedures apply more broadly to Domains and Domain Topics when used as the basis of Ad Hoc reports.

Figure 4-1 Topics and Domains Window

45


The report area.When you create a new report, the available fields appear, and the report area is empty.

3. In the list of available fields, click next to the following fields to add them to the report:

Data for each field appear as you add the columns to the table.4. Notice that the Shipped via column displays a list of numbers that seem irrelevant. Remove the column from the table by

dragging the column heading out of the report area.

5. In the list of fields, right-click the City field, and select Add as Group from the context menu.The report area refreshes and displays your selected data grouped by city.

6. In the list of fields, click Country and drag it to the Group Control icon .

The report area refreshes and displays the data grouped by both city and country. The order of the groups is determined by the order in which you added them to the report. However, you can change the order to correct it if it doesn’t make sense.

7. Drag the top-most Country heading upwards above the City group and drop it.The report area refreshes and displays the rows grouped by country and then city. The field context menu also provides this option. With the new ordering, the editor displays rows that describe stores in Argentina.

8. Review the data in the Buenos Aires group, and notice that the rows are mixed; some show data for Cactus Comidas por llevar, while others show data for Rancho grande or Océano Atlántico Ltda.

9. Drag the Name column out of the report area to remove it from the table. In the list of fields, right-click Name and select Add as Group from the context menu.

Figure 4-2 New Report in the Ad Hoc Editor

Date ordered Date shipped Order ID

Name Postal code Shipped via

Shipping charge

You can also drag to add fields from the list of fields and to rearrange columns in the table. The field context menu also provides the option to add fields.

46


The report area refreshes and displays the data grouped by country, city, and name.10. Right-click the Shipping Charge column heading and select Add Summary from the context menu.

The Ad Hoc Editor displays the totals (sum) for each name, city, and country, and displays a context menu where you can change or remove the summary function if necessary.

11. Above the report area, click Chart to view this same data as a chart. 12. Right-click the chart and select Chart Type > Pie to view a pie chart of the data.13. Above the report area, click the Table tab to return to the table view.

14. Click to include the entire data set in your table. Note that, to the right of the Crosstab tab, the words Sample Data disappear and the total for Argentina changes from $597.00 to $600.00 when the full set of data is displayed. This is because, by default, the editor only displays a subset of your data when working with a table.

15. Place your cursor over and select Save the Report.16. In the Report Name field, enter Ad Hoc Demo Report. 17. Accept the default value for Location Folder, or click Browse to select a new location.

The default location depends on the permissions granted to your user account.18. In the Description field, enter This report was created with the Ad Hoc Editor.

You have created a basic report that shows the ship date and shipping charge recorded for orders in the sample data.

Figure 4-3 Unformatted Table

Working with the full set of data gives you a clearer understanding of the final report; working with a subset of the data may improve the performance of the Ad Hoc Editor. Also note that it is easier to work with summaries in tables when only the subset is shown; this is because the summary context menu appears at the bottom of the column.

47


4.2.2 Formatting the Appearance of a Table

Next you’ll change the appearance of the table.

To format a table in the Ad Hoc Editor:1. In the Search field, enter ad hoc demo and click Search.

The Search page appears, displaying objects that match the text you entered.2. In the Repository pane, right-click the Ad Hoc Demo Report and select Open in Designer from the context menu.

This option is only available for reports that were created in the Ad Hoc Editor.The Ad Hoc Demo Report appears.

3. Click change to the right of Topic to select a different Topic or Domain.

4. Click Cancel to return to the editor without changing the Topic.5. Above the table, click the text Click to Add a Title.

The title becomes editable.6. Enter Orders and Fees by Customer.

7. Click to choose the report’s style.

The Styles window appears:

8. Select the Ocean style and click Close.9. Right-click the first Name group (Cactus comidas por llevar) and select Edit Label from the context menu.

The group label becomes editable.10. Enter Customer for the group label.11. Right-click the Date ordered column and select Edit Label from the context menu:

You can edit reports in the Ad Hoc Editor if they were created there originally, but you can’t edit reports in the editor if they originated as JRXML files.

Note that you can select a different Topic or Domain for your report. All data and formatting are lost when you select a new Topic or Domain and click Open Report. Your changes are also lost if you navigate to another page. Your changes are lost when you use the browser navigation buttons, the main menu, or the Search field.Note that your changes are preserved if you select the current Topic or report once again.

48


The column label becomes editable. Type Ordered on as the new label. Enter new labels for these columns as well:Date shipped – Shipped onShipping charge – Fee

12. Click the Ordered on column heading and place the cursor over its right-hand side. When your cursor changes to the resize icon ( ), drag the column edge to the left until the heading is no wider than the data in the column cells. Make all columns as narrow as possible.

13. Right-click the Postal code column heading and click Delete Label from the context menu. Resize the column again until it is as narrow as the data.If space is at a premium, you can remove labels from the report and make the column only as wide as the data. The name of the column in the database is displayed with a different font and background color. The label isn’t used in the report itself; it is only displayed in the Ad Hoc Editor.The last few columns are now difficult to read because they are crowded together. Adding some space might help.

14. In the list of fields, drag the Spacer into the table between each of the columns.15. Spacers can also be used to create margins. Drag the Spacer to left edge of the table.

16. Drag a Spacer to the right edge of the table, as well. You could also add the spacer to the farthest right position by clicking its arrow icon .

17. Right-click the Fee column, select Change Data Format, and click Change Data Format > ($1,234.56). The U.S. Dollars data format is applied to the Fee column.

18. Right-click the Ordered on column, click Change Data Format, and select the short date format, for example, 5/01/08. Apply the short date format to the Shipped on column, as well.The dates in the columns now appear in the short date format.

19. Use Ctrl-click to select both the Order ID field and the spacer to its right.20. Drag the field and spacer to the left-most position in the report and drop them.

21. Place your cursor over and select Hide Detail Rows to show only the summarized totals for each group. The Ad Hoc Editor applies a summary to each field depending on its datatype and inserts a spacer in the leftmost position to improve the table’s formatting.

22. Display the detail rows again from the menu.

23. Place your cursor over and select Save the Report. The Save Report As option creates a new copy of the report.

24. Accept the existing values in the dialog by clicking Save.You have now created and formatted an Ad Hoc report.

49


4.2.3 Viewing and Running a Report in the EditorWhen you have created a compelling table, chart, or crosstab, you can save it in the repository for future use. In the Ad Hoc Editor, you can:

View the report in presentation mode by clicking .

Run the report by clicking ; you can also run the report directly from the repository, as described in 3.1, “Running a Simple Report,” on page 27. When you run the report, it is displayed as a Jasper Report.

4.3 Exploring and Analyzing Data in the Ad Hoc EditorYou can use the Ad Hoc Editor to delve into your data and recognize trends and outliers by exploring and analyzing your data. The following example explores the state sales data in the Foodmart sample data that can be installed with JasperServer.

This section describes:Creating an Initial LayoutFocusing on Specific DataRefining the Crosstab

Figure 4-4 Formatted Table

Any unused space at the right of the report area is retained when you run the report.

Click and select a page size (Letter, A4, or Actual Size) if your table fits one of these formats better.

50


4.3.1 Creating an Initial Layout

To set up the crosstab and define its initial layout:1. After logging into JasperServer, click Create > Ad Hoc Report.

The Topics and Domains window appears.2. On the Topics tab, select the foodmart data for crosstab Topic, click Crosstab, and click Open Report.

The location of this Topic may depend on your system configuration. It is typically in Ad Hoc Components/Topics.The Ad Hoc Editor appears.

3. Create a crosstab. Drag:Store Country into the Column Group area.Store State into the Column Group area.Product Family into the Row Group area.Customer State into the Row Group area.Store Sales as Measure. Set the data format: right-click Store Sales in the measure label area and click Change Data Format > ($1234.56).

4. Right-click the Product Family row group label and select Expand Members.5. Right-click the Store Country column group label and select Expand Members.6. Click Save > Report enter a name, and specify a location.7. Review the data in the crosstab. Use the scroll bars if necessary.

Note that zeroes appear in many of the cells. The non-zero values mainly appear in cells where the Store State column group intersects a Store Customer row for the same state. For example, in the BC column group, every cell shows a zero except for the first, where both the Store State column group and the Customer State row group are BC.This indicates that most customers shop in their home state (the store state recorded for their purchases is the same as the customer’s home address state). There are a exceptions, but they are obscured by all the zero values. You can make the crosstab more readable and compact by pivoting the Customer State row group so that all geographical groups are on the same axis of the crosstab.

8. Right-click Customer State and select Switch to Column Group.

Figure 4-5 Crosstab of Foodmart sales totals by state and product family

51


9. Right-click Store State and select Expand Members.

Two column groups now show state names; one shows the stores’ locations, the other shows the customers’ locations. Note that fewer cells show zero values, and the crosstab is more streamlined. Any cases where a customer made a purchase in another state is more evident.The crosstab is getting easier to read.

10. Note that in Canada, BC is the only province that appears in either the Store State or Customer State: all the Canadian customers live in the the same province as the store they frequent. The same is true in the US. But in Mexico, many customers cross state lines to shop.This seems like an important outlier. In the next procedure, focus on the data from Mexico. First, save the crosstab.

11. Place your cursor over ,select Save the Report, and specify a name (Foodmart Crosstab) and location (/reports).

4.3.2 Focusing on Specific Data

To focus on specific group members and measures:1. If it isn’t open, locate and edit the Foodmart Crosstab report created in the last example.2. Right-click Customer State and select Expand Members3. Right-click Mexico and click Keep Only.

The crosstab is redrawn without data regarding the US or Canada.

4. If the filter pane is displayed, place your cursor over and select Toggle Filter Pane to hide it.Stores in DF (Distrito Federal) sell to customers in two states: DF and Mexico, which border each other. That seems trivial, but notice a similar issue in Guerrero: the Guerrero store is selling to customers in Sinaloa. Given that Sinaloa is 1000 miles from Guerrero, this may be another important outlier. Several stores are much closer to Sinaloa than Guerrero. Why are customers willing to drive hundreds of miles to visit this location?Since the crosstab only includes a single country now, the two column group summaries show identical data. Hide the Store Country column group summary.

5. Right-click Store Country and select Delete Column Summary.

6. If the filter pane is displayed, place your cursor over and select Toggle Filter Pane to hide it.Next, take a look at the sales in stores nearer to Sinaloa: Distrito Federal, Jalisco, and Zacatecas; exclude the others.

7. Select Veracruz, Ctrl-right-click Yucatan, and select Exclude.

Figure 4-6 Streamlined crosstab of Foodmart sales

Figure 4-7 Crosstab of Foodmart in Mexico

52


The crosstab now shows sales values for Sinaloa and the four nearest states.

For each customer state, the crosstab shows a sales total for all products in the Food product family. You can automatically compare them against each other and against the total for each store state.

8. In available fields, right-click Store Sales > Create Custom Field > Special Functions > % of Column Group Parent (value).A new field appears; note its abbreviated name: % CGP (Store Sales):CGP means column group parent. It compares values in column groups to their parent values and expresses each measure value as a percent of the containing column group.

Consider this example: The total for CA sales is $1000.SF sold $650, or 65% of the CA salesLA sold $350, or 35% of the CA sales

These calculated fields can be used in crosstabs that include nested column and row groups; in this case the total for the inner group is expressed as a percent of the outer group total. % Column Group Parent can also be used in tables with more than one group.To continue the above example:

The total for all states is $3000The total for CA is $1000, or 33% of the US salesThe total for WA is $2000, or 66% of the US sales.

RGP means row group parent; it’s similar to CGP but applies to row groups rather than column groups. It compares values in row groups to their parent values and expresses each measure value as a percent of the containing row group.

Consider this example:The total for the Snack Department sales is $5000.Sodas sold $4000, or 80% of the Snack sales.Chips sold $1000, or 20% of the Snack sales.

If the store also sold $2000 in another department (for example, Batteries), the percent of row group parent for snacks is 61% and is 29% for Batteries.

Note that dropping such percent of parent calculated fields in the row or column group area has no affect.9. Right-click the new custom field and click Add as Measure.

The measure appears in the crosstab. You can change the data format of the new measure to make it more readable.

10. Right-click the measure’s label, click Change Data Format, and select -1234.

Figure 4-8 Crosstab of Foodmart sales in DF, Jalisco, and Zacatecas

Figure 4-9 Crosstab of Foodmart sales and Percent of Column Group Parent

53


11. Place your cursor over and select Save the Report.

4.3.3 Refining the Crosstab

To refine the crosstab while viewing the full data set:1. If it isn’t open, locate and edit the Foodmart Crosstab report.

Click the column group labels and select Expand Members to restore the view of the crosstab shown in Figure 4-9 on page 53.The data in the crosstab is now filtered to a narrow view of the foodmart data, so you can start working with the full data set.

2. Click .Note that the words Sample Data disappear to indicate that you are working with all the available data.

3. Sort by % CGP (Store Sales); your options are Alphabetical Ascending (the default) and Numeric Ascending and

Descending. Click the to change the sorting to Numeric Ascending ( ); click to change the sorting to Numeric Ascending

When you sort a crosstab, the measures are sorted across both axis; put another way, the crosstab is sorted by both columns groups and row groups.The percent of column group measure shows that a third of the people that shop in Guerrero live in Sinaloa. In particular, the non-consumable product family seems to have many customers from Sinaloa. Take a closer look.

4. Right-click Non-consumable and select Keep Only.5. Click the arrow next to DF, Jalisco, and Zacatecas to collapse them.6. Add Product Category as a row group for more detail.7. Right-click Product Family and select Expand Members from the context menu.

The crosstab shows two categories where more than 50% of the sales in the Guerrero store were made to residents of Sinaloa: Cold Remedies and and Hygiene.

8. Click Cold Remedies, right-click Hygiene, and click Keep Only.Note that clicking the editor’s scroll bars causes JasperServer to remove focus from groups selected in the crosstab. Select a member and use the mouse scroll button to scroll to the next member.

9. Review the data in the crosstab. Use the scroll bars if necessary. In the current view:The measures show detail only for the Guerrero store; for the other states, the crosstab shows summarized values.For the % CGP measure, in Guerrero the detail for Sinaloa and Guerrero customers (47% and 53% respectively of all sales in Guerrero). In the Customer State total column, the % CGP is 13 - that is, $420.04 is 13% of all Mexican sales occurred in Guerrero.

At first glance, these numbers may seem incorrect; one might be expecting the % CGP values for Sinaloa and Guerrero customer state CGP values to roll up and equal the Guerrero CGP store state value. Instead, the Guerrero store state shows

Figure 4-10 Crosstab of Foodmart sales

54


its percent of all of Mexico, and each of its customer states show the percent of store state. For more info see 4.4.1, “Creating Custom Fields,” on page 57.You can continue to refine the crosstab to understand why the Guerrero store is selling to customers in Sinaloa. The discrepancy is slightly greater in the Cold Remedies group member; focus on it first.

10. Right-click Cold Remedies and select Keep Only.Hygiene is removed from the crosstab.

11. Add Product Name as the inner-most row group.12. right-click Product Category and select Expand Members from the context menu.

Several cold remedy brands sold mostly to Sinaloans (above 50% CGP) are selling poorly in Jalisco.

13. Note the cold remedies that are selling well to Sinaloans but not selling at all in Jalisco: Faux Products Childrens Cold Remedy, Faux Products Multi-Symptom Cold Remedy, and Steady Multi-Symptom Cold Remedy.

14. Click Faux Products Childrens Cold Remedy, shift-click Faux Products Multi-Symptom Cold Remedy and Steady Multi-Symptom Cold Remedy, and click Keep only.

Notice that Jalisco disappears; that’s because these products have never been sold in Jalisco.

15. Click to undo the last action.

Figure 4-11 Cold Remedy sales in DF, Guerrero, Jalisco, and Zacatecas

Figure 4-12 Jalisco disappears from the crosstab

55


16. Instead of clicking , you can locate the Product Name filter and reset it to include all product names.

a. If the filter pane is hidden, place your cursor over and select Toggle Filter Pane to hide it.b. Locate the Product Name filter and click the All check box to add all the cold remedies back into the crosstab. Jalisco

is restored to the crosstab.When you click the All check box, JasperServer retrieves all the values for the specified field and adds them to the filter. When the report is run, the values JasperServer retrieved are used to filter the report. Note that JasperServer does not retrieve a list of new valid values at run-time, For more information, see 4.4.2, “Using Input Controls and Filters,” on page 59. To ensure that all values are included in a report at run-time, remove the filter.

17. Place your cursor over and select Save the Report.

18. To continue further analysis, click the Product Category total for Guerrero ($314.61) to open a new instance of the Ad Hoc Editor.

19. Click Crosstab to continue data exploration or Chart to create a compelling visualization of your data.

In the above example, you explored the Foodmart data set and analyzed an interesting outlier: Sinaloans are willing to bypass a closer store (in Jalisco) in order to buy a few brands of cold remedy (Faux Products Childrens Cold Remedy, shift-click Faux Products Multi-Symptom Cold Remedy and Steady Multi-Symptom Cold Remedy). Further analysis might reveal an underlying cause:

Are these brands being regularly stocked in Jalisco, or is there a supply chain problem at this location?Are other factors contributing to the discrepancy, such as the age or gender of the customer?

and (Undo All) are only available when you have made a change in the editor since saving; the buttons are disabled when you save.

Undo can be used to cancel your last action if it JasperServer takes a long time to return.

For example, If you are working with the full data set, and a change takes too long, you can click , switch to the sample data, and make your edit again.

Figure 4-13 Crosstab of Cold Remedies sold in Mexico

56


Is this an isolated incident or a growing trend? If it’s a trend, what common characteristics of the customers or products are involved?Are the data for hygiene products similar to the data for cold remedies? Do any of the similarities shed light on the issue?

You can use the same techniques discussed in this section to analyze and explore your own data in the Ad Hoc Editor.

4.4 Additional Features of the Ad Hoc EditorThe Ad Hoc Editor offers many features that are described in the following sections:

Creating Custom FieldsUsing Input Controls and FiltersSwitching GroupsSorting TablesWorking with ChartsWorking with Crosstabs

4.4.1 Creating Custom FieldsYou can create new fields in a report by applying mathematical formulas to an Ad Hoc report’s existing numeric fields. For example, consider a report that includes both a Cost and a Revenue field. You could calculate the profit for each record by creating a custom field that subtracts the Cost field from the Revenue field. Create a custom field by selecting an existing field in the list of fields or in the report area of a table report; the Create Custom Field option appears on the context menu when you right-click a numeric field.

The Ad Hoc Editor supports three types of functions: Basic functions include addition, subtraction, multiplication, and division. You can use these functions with a constant (such as multiplying the cost by two to calculate a standard 50% markup), or you can use them with multiple fields. Select multiple fields using Ctrl-click; the columns’ borders change color to indicate that multiple fields are selected; right-click to open the context menu and create a custom field.Special functions include round, percent of total, percent of group, and rank. These functions don’t take constants, nor do they support multiple fields.Date functions can calculate the difference between two dates in a number of intervals, such as years, weeks, days, and seconds.

A custom field can only include a single function. To use more than one function to create the field you need, create two custom fields, with one building on the other. In this case, pay special attention to the order in which you create the custom fields, as this may affect the results; for example, rounding then multiplying yields different results than multiplying then rounding.

Because custom fields can build upon one another, you can create complex calculations. For example, you could divide the Profit custom field in the previous example by the Revenue field to express each record’s margin as a percent. When a custom field is the basis of another field, you can’t delete it until you delete the one that builds on it.

When working with multiple fields:You can only select basic functions and date differences.You can multiply or add any number of fields, but ordered functions (subtract and divide) and date functions can only be used with two fields at a time. For ordered operations, the order in which you select fields matters. For example, to calculate profit in the example above, click Revenue first, then Ctrl-click Cost. When you right-click and select Create Custom Field > Subtract #, the Ad Hoc Editor assumes you are subtracting the Cost field from the Revenue field. You can always change the order of fields using the context menu’s Swap Fields option.

To create a custom field based on one field:1. In the list of fields, right-click a numeric field and select Create Custom Field from the context menu.

57


2. Depending on the type of function you want to create, click Basic Functions or Special Functions.3. If you selected a basic function, select Add #, Subtract #, Multiply #, or Divide #, and then enter a number in the field that

appears; this number is the constant to use in the formula.4. If you selected a basic function, click Swap Field and Number to put the constant before the field in the formula; this is

only useful in conjunction with ordered functions. Note that you can toggle the order of the field and function from the context menu (Edit Formula > Swap Number and Field).

5. Click Create Field.The custom field appears in the list of fields.

To create a custom field based on multiple numeric fields:1. In the list of fields, Ctrl-click two or more numeric fields, right-click one of the selected fields, and click Create Custom

Field from the context menu.2. If it is not expanded, click Basic Functions, and select Add, Subtract, Multiply, or Divide.

You can only subtract or divide when exactly two fields are selected.3. Click Swap Fields from the context menu to change the order of the fields in the formula; this is only useful in

conjunction with ordered functions.4. Click Create Field.

The custom field appears in the list of fields.

To create a custom field based on two date fields:1. In the list of fields, Ctrl-click two date fields, right-click, and click Create Custom Field from the context menu.2. If it is not expanded, click Date Difference, and select a interval.

You can only subtract dates when exactly two date fields are selected.3. Click Create Field.

The custom field appears in the list of fields.

Bear the following in mind when creating custom fields:To edit an existing custom field, right-click it and select Edit Formula from the context menu. You can then choose a different function, or enter a different value (if you are editing a basic function).When you create a custom field based on a field in the table, the new field appears in the report area; when you create it from a field in the list of fields, it appears at the bottom of the list.The percent of group functions are unique among the custom functions in that they calculate values based on the grouping defined in the report. Thus, the following limitations apply:

The percent of column group function aren’t meaningful in charts and tables. In these contexts, the function always returns 100.The percent of group functions can’t be used as a group.The percent of column group parent is meaningless in table; when added to a table, it always returns the value 100.Custom fields using the percent of group functions can’t be the basis of other custom fields. This limitation also applies to the Percent of Total function.Custom fields using the percent of group functions can’t be used as filters.The summary functions for Custom fields using the percent of group functions can't be edited. This limitation also applies to the Percent of Total function.

The Round function uses the standard method of rounding (arithmetic rounding), in which decimal values greater than 0.5 are rounded to the next largest whole number.A custom field’s label is determined by the fields, constants, and functions it includes; for example, the default label for the Profit field in the example above is Store Sales - Store Cost. Right-click the column and select Edit Label to enter a more compelling name.By default, the Ad Hoc Editor supports only two decimal places. If your custom fields return data that are significant to the third decimal place, you can add new masking options by editing configuration files. For more information, refer to the JasperServer Administrator Guide.

58


You can’t delete a custom field that is used in the report area. First remove the custom field from the report area and then delete it from the list of available fields.

4.4.2 Using Input Controls and FiltersJRXML Topics and Domains use different mechanisms for narrowing down the data they return:

JRXML Topics can contain parametrized queries. The parameters can be mapped to input controls that allow users to select the data they want to include. Domains (and Domain Topics) can be filtered by selecting fields in the Domain and specifying comparison values. The filters can be configured to allow users to select the data to include.Within the Domain design, filters can also be defined; they're never displayed in the editor or when the report is run.

In the Ad Hoc Editor, you can also define filters regardless of whether you are working with a Domain or Topic.

Input controls and filters interact seamlessly. For example, when a JRXML Topic includes input controls that prompt users,

and you also create filters, the Ad Hoc report has both input controls (displayed by clicking ) and filters (displayed in the filters pane). Since this can result in a combination of input controls and filters that don’t return data, JasperServer refreshes the editor against both the filters and the input controls. Nevertheless, some combinations of filters and input controls may result in no data being returned.

For more information about:JRXML Topics and input controls, see 5.2.9, “Adding Input Controls,” on page 90.Domain Topic filters, see 4.5.1, “Choosing Ad Hoc Data From a Domain,” on page 67.

4.4.2.1 Using Input Controls

In the Ad Hoc Editor, you can display the input controls defined in the Topic as visible to users. You can accept the queries’ default values or enter other values.

The Ad Hoc Editor indicates that the report has input controls by displaying as active. Click this icon to select new values or to save values as the new defaults for this report.

For more information about:JRXML Topics and input controls, see 5.2.9, “Adding Input Controls,” on page 90.Domain Topic filters, see 4.5.1, “Choosing Ad Hoc Data From a Domain,” on page 67.

To edit the values for a report’s input controls:

1. Click .

If your results are empty but don’t understand why, click > Toggle Filter Pane (if it is hidden) and click . You may find a combination that explains an empty result set; for example, if you have both a standard filter (set against a Country field) and a complex filter (set against both Country and State).

59


A window listing the current values for the input controls appears.

2. Select new values.3. If appropriate, select the Set these values as defaults when saving report option.

When this option is selected, the selected values are made the default values when you save the report. If you do not select the option, the previous default values are used.

4. Click OK. The report appears. The data that appears is determined by the new values.

4.4.2.2 Using Filters

Filters can be defined at three levels: In the Domain Design.When creating a report from a Domain (in the Choose Ad Hoc Data wizard).In the Ad Hoc Editor (even when the report is based on a JRXML Topic).

To create a filter:1. Right-click a field in the list of available fields and click Create Filter.

A new filter appears in the filter pane. If the filter pane was hidden, it appears when you create a new filter. 2. Depending on the datatype of the filed you selected, the filter maybe multi-select, single-select, or text input.3. Use the fields in the filter to change its value.

4. Click to expand the filter and change the filter’s operator.

5. Click to remove the filter.

6. Click to hide the filter’s details. Click to display them once more.7. Click the All check box to select all values currently available in the data set.

Note that the All check box doesn’t guarantee that all values will be selected every time the report is run. Instead, the check box is a shortcut to help you quickly select all the values currently available in the data set. To ensure that all values appear in the report whenever it is edited or run, remove the filter entirely. For more information, see 4.4.2, “Using Input Controls and Filters,” on page 59.

You can also create a filter from groups in tables and crosstabs, or from columns in tables. On the Chart tab, you must right-click the field in the list of those available.

Figure 4-14 Input Controls in the Ad Hoc Editor

60


When you change a filter, JasperServer uses the new value to determine the data to display. Note that if you only change the the operator in a single-select filter, JasperServer doesn't apply the filter automatically; press Enter or Tab to apply the new values. You can also click the current value to force the editor to update your view

4.4.2.3 Input Controls and Filters Availability

Input controls and filters can appear in both the editor and when the report is run:Input controls can be set to be hidden or displayed:

Input controls set to prompt are always displayed in the editor and when the report is run.Input controls that aren't set to prompt are always hidden in the editor and when the report is run.

Filters defined in the domain design are always hidden in the editor and when the report is run.Filters created in the Choose Data Wizard can be set to be hidden or displayed:Filters set to prompt are always displayed in the editor and when the report is run.Filters that aren't set to prompt are displayed in the editor but hidden when the report is run. Note that users can still remove the filter while in the editor, allowing them to see all the data unfiltered.

When a report is run, any input controls or filters that are set to prompt are available; if they aren't displayed directly on the

report page, click to view them.

To determine whether an input control is displayed:1. Edit the Topic and, on the Controls and Resources page, click the input control.2. Click Next, and click the Visible check box to change whether the input control appears. For more information, see 5.2.9,

“Adding Input Controls,” on page 90.If you don’t provide a default value for the input control, users are prompted to select a value when they create a report against the Topic.

To determine whether a filter defined in the Choose Ad Hoc Data wizard is editable:1. Create a new report against a Domain, and on the Filters tab, create a filter and click OK.2. To the right of the new filter, click the Prompt? box to remove the check if you don’t want users to edit this filter’s value

in the editor.Note that they can still remove the filter, allowing them to run the unfiltered report. Such filters can be helpful in improving the report's initial performance by reducing the amount of data the report returns by default. However, if your aim is to disallow users from seeing the full data set, user data-level security instead. For more information, see 4.4.2.3, “Input Controls and Filters Availability,” on page 61. Input controls in a JRXML Topic or filters defined in the Domain design can also be used, as they can be hidden from end users.You can’t change whether a Choose Ad Hoc Data wizard filter is displayed once the report is created.

4.4.3 Switching Groups

In the Ad Hoc Editor, the icon lets you change how the groups are displayed. Depending on the type of report you are viewing, the behavior varies:

Filters are also created when you right-click a group member in a crosstab and select Keep Only or Exclude. The filter pane does not automatically open in this case. When you create a filter against an inner group, the filter that appears may be created as a complex filter; a complex filter can’t be edited but it can be removed. Note that similar complex filters also appear in the Ad Hoc Editor if a Choose Ad Hoc Data wizard filter was created and set to not prompt for values.

Filters defined in a Domain design are always hidden in the editor and when the report is run. Filters created in the editor are always available in the editor and when the report is run.You can learn more about how filters and input controls interact in the editor by walking through the data exploration tutorial with the filter pane open. For more information, see 4.3, “Exploring and Analyzing Data in the Ad Hoc Editor,” on page 50, and skip step 6 in section 4.3.2, “Focusing on Specific Data,” on page 52.

61


In crosstabs, JasperServer moves the row groups to column groups and vice versa. This action is also referred to as pivoting. This option is only available for crosstabs that have both a column group and a row group.In charts, JasperServer displays the alternate group. This option is only available for charts that have a column group. When multiple row or column groups are defined, the Chart tab displays the outermost group. In tables, JasperServer displays the alternate group. This option is only available for tables that have a column group. When multiple row or column groups are defined, the Table tab displays the first group in the set (the outermost group).

By default, a table or chart is grouped by the column group; click to group it by the row group.

Put another way, for this feature to be available for tables and charts, the report must have been edited on the Crosstab tab to add a column group. Otherwise, there is no alternate group to switch to.

When you design a table or chart and then view the Crosstab tab, you only have a row group defined. Drag a field into the column group to complete the crosstab.

4.4.4 Sorting TablesIn the Ad Hoc Editor, you can sort the rows of a table by one or more fields. You can also sort crosstabs; for more information see Figure 4-14 on page 65.

To sort a table:

1. Click .The Sorting window appears. If the table is already sorted, the window shows the fields that are used.

2. To add a field, click Add Fields.The Fields window appears with a list of available fields. It only lists fields that are not already used.

3. Select one or more fields to sort by, and click OK. Press Ctrl and click to select multiple fields.The Sorting window reappears with your selected fields.

4. To arrange the sorting precedence of the fields, select each field in the Sorting window and click the Up, Down, Top, or Bottom icon.

5. To remove a field, select it and click .6. Click OK.

The table updates to display the rows sorted by your selected fields.

Create the table or chart with the most important grouping field, then click Crosstab to add another compelling field as the column group; the field you select is now available as an alternate group in the table and chart.

Click Table or Chart to return to your initial view, and then click to display the alternate group.For example, you could create a bar chart that showed your sales by region. By switching to the Crosstab tab, you could add Client Industry as the column group. Back in the Chart tab, switch the groups to display the sales data grouped by Client Industry. This comparison can help you identify trends and outliers in your data.

When sorting a table:You can click a field in the list of fields and select Use for Sorting from the context menu. In this case, the table is sorted by a field that isn’t in the table; you may want to note the sorting fields in the title.If a column is already being used and you want to stop using it or change the sorting, right-click the column and select Change Sorting from the context menu. In either case, the Sorting window appears and you can define the sorting as above.

To sort a crosstab, click the icon next to a measure’s label. For more information, see 4.4.6, “Working with Crosstabs,” on page 65.

62


4.4.5 Working with Charts

4.4.5.1 Chart Types

Charts are graphical representations of your data. The Ad Hoc Editor can create both summarized and unsummarized charts:Summarized charts show data grouped and summarized:

Bar. Compares values displayed as bars.Pie. Compares values displayed as slices of a circular graph.Line. Compares values displayed as points connected by lines.Area. Compares values displayed as shaded areas.

Unsummarized charts show each data point individually, and don’t support grouping:Scatter. Compares values expressed as pairs of values that determine the position of a point on the chart.Time Series. Compares values based on times or dates associated with the data.

When you create a chart, you generally indicate how to arrange the data by specifying:A group field. Similar to the table's grouping option, a chart’s group field determines how data are categorized. For example, in a bar chart, the category field determines how the bars are grouped; in a pie chart it determines what each slice represents.Note that time series and scatter charts don't support grouping; instead, each data point is mapped individually. The data aren’t summarized.Measure fields. Measures are the other data in your chart. They determine the length of bars, size of pie slices, location of points (in line charts), and height of areas.

4.4.5.2 Designing Charts

Charts have different layout and format options than table or crosstabs. Keep these points in mind:By default, the Ad Hoc Editor creates a bar chart. You can select a different type of chart at any time.The Ad Hoc Editor automatically hides all but the first measure if you change to a pie chart, since pie charts can only show a single measure. For each type of chart, the context menu provides these display options:

Type Description

All Chart Types Regardless of the type of report, you can:Remove Gradient or Apply Gradient. Whether the background color should graded or solid. When the gradient is removed, the background is filled with a solid color. Remove Background or Fill Background. Whether the background should be filled.

Note that the gradient doesn’t appear when you run the report.

Bar Chart When creating a bar chart, the context menu provides these options:Flat Bars or 3D Bars. Whether to use a flat, two dimensional appearance or a three dimensional (3D) appearance.Horizontal Bars or Vertical Bars. Whether the bars are parallel to the width or height of the chart. Stacked or Simple Series. Whether multiple measures of each group are depicted as individual bars or as portions of a single bar.

Note: A series chart displays multiple measures for each group value.

Pie Chart When creating a pie chart, you can indicate whether to use a Flat Pie (which is two dimensional), or the default, which is three dimensional (3D Pie).

Line Chart When creating a line chart, you can indicate whether to display markers at each data point and lines that join them. Select Hide Lines or Hide Points to remove the indicators from the chart.

63


Before any fields are added to the chart, the Ad Hoc Editor displays a simple placeholder with the legend displaying a single entry: No Data. As you add groups and measures, the mock-up changes to reflect the data in the chart. For example, when you add a group to a pie chart, the pie displays the correct number of pie slices; when you add a measure to a bar chart, the Y-axis units and values show the range of values in the measure you selected. Once you have added at least one group and one measure, the mock-up is replaced by the chart, and you can save or run the report.Fields can be added as groups or measures. To add a field as a group, drag it to the group target to the left of the report area. To add a field as a measure, drag it into the report area or right-click it in the list of fields and select an option from the context menu. Note that there is no for adding fields, and you can add fields more than once; for example, you can add a field as both a measure and a group.You can rename the measures displayed in your chart by right-clicking the measure’s label in the legend and selecting Change Legend Label from the menu that appears. The text you enter replaces the field’s name. This option is also available on the chart context menu.If you change the measure’s summary function, the label updates to reflect the change. If you change the summary function back, the last name entered for that measure with that summary function appears.You can increase a chart’s size to improve its legibility or you can decrease its size if it’s intended for use in a JasperServer dashboard or JSR-168 compliant portal, such as Liferay. When you place your cursor over the right-hand or bottom edge of the chart, the resize arrow appears; click and drag the edge of the chart to increase or decrease its size.For more information about portal integration, refer to the JasperServer Administrator Guide.By default, the page is set to Actual Size, which resizes the page to fit your chart’s dimensions.

When you place your cursor over and click A4 Size or Letter Size from the menu, the Ad Hoc Editor limits the size of the chart to the selected page size. If you resize the chart to be larger, the Ad Hoc Editor snaps the chart back to the maximum allowable size in either dimension (height or width).

If space is at a premium in your chart, or if you want to use it in a portal, place the cursor over and click Strip Margins. The Ad Hoc Editor removes the margins, giving your chart more horizontal and vertical room. Note that when you strip the margins of a chart set to the Actual Size page size, the change isn’t reflected in the Ad Hoc Editor. You can see the change by setting the page size to Letter or A4. A scatter chart uses Cartesian coordinates to display values as points whose locations are determined by two variables you select. One variable determines the horizontal position and the other determines the vertical position. It plots paired values against one another. Time series charts plot your data against the passage of time. They can help you understand the nature and underlying context of your data, identify trends, or forecast future results. In a time series chart, the horizontal axis must represent a date or time field, such as Purchase Date. If you add a field to the horizontal axis that has a datatype other than a date/time, the Ad Hoc Editor renders the chart as best it can, but the result is likely to be meaningless.Unsummarized charts (scatter and time series) can only be run or saved if the fields selected for the X and Y axis are appropriate:

For scatter charts, both fields must be numeric.For time series charts, one field must be a date or date/time, and the other must be numeric.

Area Chart When creating an area chart, you can indicate whether the groups should be displayed as transparent overlays or as solid areas. Select Stacked Series to display the groups as solid areas arranged vertically, one on top of another; select Simple Series to display groups as transparent overlays.As compared to line charts, area charts emphasize quantities rather than trends.

Scatter When creating a scatter chart, you can indicate whether to display markers at each data point and lines that join them. Click Hide Points to remove the marker at each data point. Click Show Lines to add lines that join the data points.

Time Series When creating a time series chart, you can indicate whether to display markers at each data point and lines that join them. Click Show Points to add a marker at each data point. Click Hide Lines to remove the lines that join the data points.

Type Description

64


You can hide legends and labels to allow the chart more space, or you can show them to make the chart easier to understand. In the chart context menu, click Legends and Labels, and specify whether to display the legend (generally, the list of measures in the chart; for pie, it is the list of groups), the group title (which identifies the name of the group field), or measure titles (which identifies the measures).Right-click a measure in the legend to change its label.In bar, line, and area charts that display multiple measures, you can change the order of measures by dragging the legend entry right or left. This reorders the measures in each group. While the order of measures is changed, the order of colors is not. Thus, the measures change color as they are reordered. This can be helpful improving a chart’s legibility and visual appeal.Remove measures from the chart using the legend or chart context menu. If the chart only displays a single measure, right-click the chart and select Remove Measure. If the chart displays multiple measures, the context menu lists them under the Measures menu option. The measures are listed in the order they appear within your groups. On the chart context menu, click Measures > [Measure Name] > Remove Measure (where [Measure Name] is the name of the measure you want to remove).

Remove a chart’s group by right-clicking the chart and selecting Remove Group from the context menu. You can also right-click a different field in the list of fields, and click Replace Group, or simply drag the new group field and drop it on the group control.When working with a chart that displays two measures with very different ranges of values, the chart may be difficult to read or understand. To make the ranges of values more similar, create a custom field that multiplies or divides one of the measures. Consider the case where you are comparing the number of items sold (values ranging from 0-50) and the total sales revenue for each product (values ranging from 0-50,000), you could create a custom field that divided the revenue measure by 1000. Adding this measure in place of the actual revenue measure yields a chart in which the two measures are depicted in closer scale. The new chart is both easier to read and more appealing. Jaspersoft recommends that you note such changes in the legend label or title.To add a field in a specific position in a chart, you can drop it in the legend in the desired location. The new measure appears in the correct location in the chart.

4.4.6 Working with CrosstabsCrosstabs have different data, layout, and format options than tables or charts. Keep these points in mind:

Fields can be added as row groups, column groups, and measures. To add a field, drag it into the crosstab or right-click it in the list of fields and select an option from the context menu. Note that there is no for adding fields, and you can add fields more than once; for example, you can add a field as both a measure and row group.Measure labels are displayed to the left of the first column group. To edit a measure, right-click its label.Row and column groups are arranged in hierarchies. Drag the group headings to rearrange the hierarchy; you can also right-click a heading and select a Move option from the context menu or press the cursor keys. Rearranging the groups may change the preview data in the editor.When the crosstab includes more than one row group or more than one column group, click the arrow in each heading cell to expand the inner group. Click the arrow again to collapse the inner group once more.When you collapse a group, its summary is automatically displayed; this prevents invalid crosstab layouts in which there is nothing to display for some totals if the the summary has been deleted previously.You can pivot a crosstab in two ways:

Pivot the entire crosstab, click . The row and column groups switch places. For more information, refer to 4.4.3, “Switching Groups,” on page 61.Pivot a single group:

To pivot a single row group, right-click it and select Switch To Column Group.To pivot a single row group, right-click it and select Switch To Row Group.

The Measures menu also allows you to change the summary function and data format. It is available from the chart context menu as well as from the legend.

65


You can use the slice menu to keep or exclude group members in a crosstab. To slice, right-click a group member and select:

Keep Only to remove all groups except the selected one from the crosstab.Exclude to remove this group from the crosstab.

Use Ctrl-click and Shift-click to select multiple groups to keep or exclude. Note that you can select multiple row groups or multiple column groups; you can't slice by both row groups and column groups at once. Compare slice to drill-through, drill to details, and filtering. For more information on drill-through. see the JasperAnalysis User Guide; for more information on filtering, see 4.4.2, “Using Input Controls and Filters,” on page 59.Measures are arranged in cells. You can add any number of measures. All the measures appear together in every cell. To rearrange the measures, drag them in the measure label area; you can also right-click a measure label and select a Move option from the context menu, or press the up and down arrow keys on your keyboard. All row and column groups are summarized automatically:

To turn off a group summary, right-click any heading in the group and select Delete Row Summary or Delete Column Summary from the context menu. Note that this option is only available for the outermost group on either axis (that is, either the outermost row group or the outermost column group).To select the summary function and data format for a measure, right-click the measure label and select from the context menu. Note that you can’t change the summary function on custom fields that calculate percents (Percent of Total, Percent of Column Group Parent, and Percent of Row Group Parent).The summary functions for numeric fields are Maximum, Minimum, Average, Sum, Distinct Count, and Count All. Distinct Count is the number of different items in the row or column; Count All is the total number of items. For instance, if there are 3 widgets of type A and 3 widgets of type B, Distinct Count is 2 and Count All is 6.

On the Crosstab tab, by default, the editor displays each row and column group in a collapsed state. This means that you can see the totals for the group, but not the measures for its individual members. To see measures for a group’s members, right-click the group label and select Expand Members. When a group’s members are expanded, select Collapse Members from the same menu to hide the measures. Collapsing an outer group also collapses its inner groups. The Expand Members and Collapse Members options are only available for outer-most groups or inner groups nested in an expanded outer group.

On the Crosstab tab, by default, the editor only displays a smaller, sample set of the data in your crosstab. Click to view the full set of data.By default, a crosstab is sorted in alphabetical ascending order according to its group member names. Only one measure can be used for sorting at any one time. You can sort it by any of its measures:

Click to change the sort order from the default. The icon changes to and the crosstab is sorted in ascending numeric order by its measure values.

Click to switch the numeric order from ascending to descending. The icon changes to and the crosstab’s sort order is reversed.

Click to return to the default sort order. The icon changes to and the crosstab is once again alphabetically sorted by its group names.

When you sort by a measure, the entire crosstab is reordered: both columns and rows reflect are re-sorted within each group. When the crosstab includes more than one row group or more than one column group, the inner groups are also sorted according to your selection.Many of the layout and formatting options set manually in tables are set automatically in crosstabs. In particular, row and column sizes are fixed and no spacer is available.Hover your cursor over a measure value or total and notice the underline that indicates a hyperlink. Click the hyperlink to open the Table tab of the Ad Hoc Editor in a new window or tab (depending on your browser and its settings). This new table is filtered to only show rows that were rolled up to create the hyperlinked value you selected. Its columns are created from the fields used as measures in the crosstab. This new instance of the editor is completely independent of the original crosstab: you can change it and save it without changing the crosstab.

For more information on working with crosstabs, see 4.3, “Exploring and Analyzing Data in the Ad Hoc Editor,” on page 50.

66


4.5 Creating a Report from a DomainLike Topics, Domains are created by data analysts and JasperServer administrators for use by others to access data more conveniently. For report makers, Domains differ in that they give more flexibility in choosing fields from the database and allow some filtering of the data before it is included in a report.

Domains also allow you create reports that prompt the reader for input that determines what data is presented. For example, if a Domain includes all sales data for a company, a report based on that Domain could present detailed information grouped by postal code and have an input control to let the reader select the geographic area, such as a US state.

For a more complete description of how to create Domains, see section 6.2, “Example of Creating a Domain,” on page 117.

4.5.1 Choosing Ad Hoc Data From a DomainWhen you create an Ad Hoc report based on a Domain, the Choose Ad Hoc Data wizard leads you through the steps of choosing fields and filters. The following example shows how to use the wizard to create a simple report from a Domain. For complete information on all of the options and settings available for designing reports, see 4.5.2, “Using the Choose Ad Hoc Data Wizard,” on page 71.

To create a basic report from a Domain: 1. On the Home page, click Create > Ad Hoc Report.

The Ad Hoc Editor opens to the Topics and Domains window. 2. Click the Domains tab.

The tab opens with a list of the available Domains. The frame at the bottom shows you the description of the Domain currently selected in the list.

3. Select the Simple Domain for your report, click Table, and click Choose Data. The Choose Ad Hoc Data wizard opens to the Data page.

Figure 4-15 Topics and Domains Window With the Simple Domain Selected

67


On the Data page, select the fields that appear in the Ad Hoc Editor. You can select whole sets or individual items within a set. A set appears in the Ad Hoc Editor as a set of fields that can be added together to a table.

4. In this example, expand each set and drag the following fields into the Selected items list:Accounts set: Account Name fieldOpportunities set: Drag the whole set, but then drag back the Sales Stage fieldUsers set: First Name and Last Name fields

Fields always appear within their set, so a set is duplicated in the list of selected list if any of its fields are moved.

5. Click Next.The Choose Ad Hoc Data wizard shows the Filters page; you can set limits on the data that are retrieved and displayed in your table.

Figure 4-16 Choose Ad Hoc Data Wizard: Data Page

If a Domain is configured for secure access, you see only sets and items for which you have permission. Other items might not be visible to you, even though another user can see them if he used the same Domain. Conversely, the fields that you can see might include ones that other users can’t see.

Figure 4-17 Selecting Item Sets

68


6. For this example, select Amount by clicking its arrow icon .The item appears in the Condition Editor.

7. In the Condition Editor’s Comparison drop-down, select the operator for the comparison: is Greater than or Equal to.8. In the Values field, enter the value to compare the data against: 10000.9. Click OK.

The complete filter condition appears in the Current Conditions list. In this example, the filter selects only the rows of data where the opportunity amount has a value of 10,000 or more.

10. Click Next.The Choose Ad Hoc Data wizard shows to the Display page.On the Display page, you can edit the table and field names that will appear in the Ad Hoc Editor so that they are more appropriate for the report’s audience. The names in the Domain are often appropriate as is, but this Display page gives you a final opportunity to change them.

11. For this example, double-click the Amount item and change its display name to Opportunity Amount.

Figure 4-18 Defining a Filter on an Item

If a Domain is configured for secure access, the values displayed in the condition editor are the ones for which you have permission. Other values might not be visible to you, even though other users see them if he used the same Domain. Conversely, the values that you can see might include ones that another user can’t see.

69


Note that the display names are shown on the left side of the page.12. If you want to create different reports with the same settings, you can save them as a Domain Topic, as described in

section 4.5.3, “Creating Topics from Domains,” on page 73.13. To confirm all the selections made in the Choose Ad Hoc Data wizard and begin creating a report, click Open Report.

The Ad Hoc Editor appears, and the list of fields shows the item sets selected in step 4. 14. Design your report in the Ad Hoc Editor, as described in section 4.2.1, “Selecting the Content of a Report,” on page 45

and 4.2.2, “Formatting the Appearance of a Table,” on page 48.In this example:c. Drag the Opportunities set to the report area to add all its fields as columns.

They are added (with the display name) in the order you defined on the Display page in step 4. d. Click the arrow next to the Spacer item, e. Expand the Users set and click the arrow next to the Last Name field. f. Expand the Accounts set and drag the Account Name item to the grouping icon.Notice that all amounts are greater than 10000, as determined by the filter you defined.

As shown in this example, creating an Ad Hoc report based on a Domain gives you more flexibility in selecting data and can subsequently speed up the design of the report itself.

Figure 4-19 Changing the Display Name of an Item

Figure 4-20 Ad Hoc Editor with Fields Configured for Report

70


15. In top right corner of the list of available fields, click select to change the fields used in the report. The Change Field Selection window appears, displaying two lists of tables. The tables on the right are those that were selected when the report was created; the ones on the left are the other tables available in the Domain. Note that you can only select tables in the join tree chosen when you created the report originally.

16. Expand a table to see its fields; fields that are used in the report area, as filters, or for sorting appear gray to indicate that they can’t be removed from the report.Drag a table from the Available list to the Selected list to add it to the report. When you remove a table, all the its fields are removed except those that are in use.You can also drag individual fields to add or remove them.

17. Drag a table from the Selected list to the Available list to remove it from the report.

18. If you add or remove a field accidentally, click to undo the change.

4.5.2 Using the Choose Ad Hoc Data WizardThis section gives more detail about the four pages of the Choose Ad Hoc Data wizard:

The Data Page – Choose the fields to make available in the Ad Hoc Editor.The Filters Page – Define a filter on any field, with the option of prompting for user input, or to compare fields.The Display Page – Change the order and names of fields that will appear in the Ad Hoc Editor.The Topic Page – Save your settings as a Domain Topic.

You must first select some fields on the Data page, but the other three pages are optional and can be completed in any order. Click Done at any time to begin designing your report.

4.5.2.1 The Data Page

Use this page to choose fields and sets of fields to use in your report or make available in your Domain Topic.The left-hand list displays the sets of fields in the Domain. Use the controls in the tree to close or expand each set.The list on the right-hand side shows you the items you have selected. You can move a field or set back and forth between the lists by dragging the item, double clicking it, or selecting it and clicking an arrow button.If you move an individual field out of a set, it appears in a set of the same name, as shown in Figure 4-17 on page 68. If you do not want sets, use the settings on the Display page.You can change Domains on the drop-down list above. Doing so removes all settings and updates the list of fields.Some Domains define sets that are not joined. When you select a field from one set, the unjoined sets aren’t available.

4.5.2.2 The Filters Page

The Filters page provides powerful functionality for designing reports within JasperServer. You can define filters to limit data that appears in a report and to define whether a report should prompt users for input on a given filter. They are similar to input controls.

You can define a filter on a field that you do not plan to use in the report. The filter is still applied and only data that satisfies all defined filters will appear in the final report. For example, you can filter data to select a single country, in which case it doesn’t make sense for the Country field to appear as a row, column, or group.Select a field in the left-hand list and click Create Condition to begin defining a filter on that field. Alternately, you can click the arrow next to the field name or double-click the field name.In the Condition Editor, the comparison operator and value operand depend on the datatype of the field and on the actual data that exist for the field. Choose the operator and operand for comparison, then click OK to define your filter.

71


Text fields have both substring comparison operators such as “starts with” or “contains” and whole string matching such as “equals” or “is one of.” When you select a whole string matching operator, the dialog displays a list of all existing values for the chosen field retrieved in real-time from your database. If there are more than 50 values to display, use the

search controls to the left and click to narrow your list of available values. For multiple value matching, double-click the available values to select them. You can perform multiple searches and select values from each list of results.The list of Current Conditions shows all the filters you have defined. When the Prompt? check box is checked, the

selected filter is available to end users when they run the report. On the report page, users can click to enter a comparison value for this condition; when the user clicks Apply or OK, the report preview refreshes with data that match the condition. The value defined here is the default. The condition is available as a prompt even if the filtered field does not appear in the report. For example, the final report might present data for a single country, but the country is chosen by the user. Once defined, filter prompts can be modified in the Ad Hoc Editor, as explained in 4.4.2.1, “Using Input Controls,” on page 59.Note that when the is Prompt? check box isn’t checked, the condition is still available in the Ad Hoc Editor, but users can only remove it; they can’t edit it; such a filter is hidden when the report is run.The note at the bottom of the current conditions reminds you that data rows much match all conditions. In other words, the overall filter applied to your data is the logical AND of all conditions you have defined.Click a row in the list of Current Conditions to make it editable again in the Condition Editor. Click OK to save your changes. After selecting a row, you can also click Delete Condition to remove it from the list.To define a filter that compares two fields of the same datatype, select the second field using Ctrl-click, then click Create Condition. This button is only enabled when two compatible fields are selected. After you click OK, you can edit and delete it as with other conditions. Not that such filters can’t be presented to your users when they run the report.The maximum number of items that can be displayed in the list of values in the Condition Editor is configurable. For details, see the JasperServer Administrator Guide.

4.5.2.3 The Display Page

Use the Display page to change the default name and order of the fields as they should appear in the list of fields in the Ad Hoc Editor. You can always change the field labels and ordering in the Ad Hoc Editor, but setting them here will make them available for reuse in a Domain Topic. See Figure 4-19, “Changing the Display Name of an Item,” on page 70.

To change the order of fields, click once anywhere in a row and use the arrow buttons to move it up, down, to the top or bottom. Fields may be moved only within their set, but sets as a whole may be also be moved.To change the display name of a field or set, double-click anywhere in the row and type the new name in the text box. A field name becomes the label for the row, column, or measure that you create from the given field.Sets and the fields they contain appears in the list of fields in the Ad Hoc Editor. Sets are not used in reports but can be used to add all their fields at once, thereby speeding up report creation.

Figure 4-21 Condition Editor on the Filters Page

72


If you don’t want to use sets in the Ad Hoc Editor, select the check box Show items as simple list in designer above the table of display names. You can now rename the fields and move them in any order.

4.5.2.4 The Topic Page

On the Topic page, you can give your settings a name and a description to be saved as a Domain Topic. Thereafter, you can create different reports from this Domain Topic, using all the same fields, filters, and display names you have defined. You can also edit the Domain Topic to change any of the settings you made in the Choose Ad Hoc Data wizard.

After you enter a name for your Domain Topic, it is saved when you click Create Report from any page in the wizard.By default, Domain Topics are saved in the standard Topics folder. This corresponds to the Ad Hoc Components > Topics location in the repository; JRXML Topics and Domain Topics in this folder appear on the Topics tab when you start a report. Do not modify this folder name.The description text is associated with the Domain Topic in the repository. It is displayed at the bottom of the Topics tab and when browsing the repository. Enter an informative description that helps users identify this Domain Topic.

4.5.3 Creating Topics from DomainsIn some circumstances, it is important to create a Topic based on the Domain and data settings you chose. In other circumstances, creating a Topic isn’t necessary. The main consideration is how reports based on the Domain will be used.

The following table explains your choices.

If you want to … Then do this Explanation

Create a single-use report from the Domain with your settings.

Click Open Report after defining your settings in the Choose Ad Hoc Data wizard, then format and run your report.

When you click Done, your field selections appear in the Ad Hoc Editor and you can create reports from them, but the settings themselves are not saved.

Run a report repeatedly as is or with prompting for new input, or make very similar reports in the Ad Hoc Editor.

Click Open Report after defining your settings in the Choose Ad Hoc Data wizard, then format and save the report in the Ad Hoc Editor.

Once you save a report, users can run it repeatedly and be prompted for input each time if you defined filters with prompts. Users with permissions may also open it again in the Ad Hoc Editor. See section 4.2.2, “Formatting the Appearance of a Table,” on page 48.

Reuse your field, filter, and display settings on this Domain to create new reports with different formatting.

Before you click Open Report, save your settings as a Domain Topic on the Topic page of the Choose Ad Hoc Data wizard. Start a new report and choose your Domain Topic from the Topics tab.

See section 4.5.3.2, “Saving Domain Settings as a Topic,” on page 74. Domain Topics are saved in JRXML format in the repository. They appear on the Topics tab when you start a report.

Be able to modify one or more of the settings you made in the Choose Ad Hoc Data wizard.

Before you click Open Report, save your settings as a Domain Topic. Find your Domain Topic in the repository and open it in the Edit Domain Topic dialog.

Domain Topics can be edited as described in section 4.5.3.3, “Editing a Domain Topic,” on page 75. After you save your changes, you can create reports based on the modified Domain Topic.

Run reports from the same repository data source but with different Domain settings, such as derived fields and different joins to make new fields available in a report.

Edit the Domain and save it with a new name. Then start a new report and choose your data from the new Domain.

Domains provide advanced functionality such as table joins and derived fields based directly on a data source. Domains usually require administrator permissions to create and modify. For more information, see section 6.5, “Editing a Domain,” on page 135.

73


4.5.3.1 Access Permissions in Domain Topics

If other users run reports from your Domain Topic and the Domain is configured for security, it is important to consider everyone’s access permissions.

You might not have access to all of the fields in the Domain nor to all the data in those fields. There may be fields that can be seen only by other users, and in the fields that you can see, there may be data that is hidden from you. When you save your Domain as a Topic, only the fields that you selected appear in the Domain Topic. When you run a report from the Topic, only the data that you can access in those fields appears. When others run reports from the Topic, they see those of your fields to which they have access and the data in those fields that they can access.

For example, in a Domain, user Tomas can access fields B-C and data rows 1-3; Anita can access fields C-E and data rows 2-5. Tomas uses the Choose Ad Hoc Data wizard and saves a Domain Topic based on the Domain. When Tomas and Anita run reports, they see different combinations of fields and the data in them.

Even though Anita has permission to see more fields, they are not available to her because Tomas did not have access to them when he created the Domain Topic. However, Anita does have permission to see more data than Tomas, so when she opens or runs the report, the field she does see has more rows than when Tomas views the report.

4.5.3.2 Saving Domain Settings as a Topic

To save your settings in the Choose Ad Hoc Data wizard as a Domain Topic:1. While making selections in the Choose Ad Hoc Data wizard, navigate to the Topic page. 2. Enter a Topic name and description.

Do not change the location folder. The default /adhoc/topics folder makes the saved Domain Topic available on the Topics tab when you select Create > Ad Hoc Report.

Fields Data

Tomas’s report from his Domain Topic B C 1 2 3

Anita’s reports from the same Domain Topic C 2 3 4 5

See section 7.4, “The Domain Security File,” on page 155 for a technical explanation of data security for Domains. See the note in section 6.5, “Editing a Domain,” on page 135 about the impact of editing a Domain or Domain Topic.

74


3. If your data selections, filter definitions, and display settings are complete as well, click Done. Otherwise, navigate to the other pages to finish making your settings.Your Domain Topic name and description are preserved, and the Domain Topic is created when you subsequently click Done anywhere in the Choose Ad Hoc Data wizard. You can also change the name and description by returning to this Topic page anytime before clicking Done in the wizard.The new Topic appears in the Ad Hoc Components > Topics folder. While its repository type is Domain Topic, it appears when the Search page is filtered to show reports:

4.5.3.3 Editing a Domain Topic

Editing a Domain Topic modifies the settings that were defined in the Choose Ad Hoc Data wizard when creating it.

Figure 4-22 Entering Information Needed for Saving a Domain Topic

Figure 4-23 Choose Ad Hoc Data Settings Saved as a Domain Topic

75


To edit the settings in a Domain Topic:1. Select View > Repository and search or browse for the Domain Topic you want to modify.

Domain Topics are usually kept in the Ad Hoc Components > Topics folder.2. Right-click the Domain Topic and select Open in Designer... from the context menu.

The Domain Topic opens in the Edit Domain Topic wizard, which has the same features as the Choose Ad Hoc Data wizard.

3. Follow the guidelines in section 4.5.2, “Using the Choose Ad Hoc Data Wizard,” on page 71 to edit the Domain Topic as needed.

4. To save your changes to the selected Domain Topic, click Save on any page.

To save your changes as a new Domain Topic, navigate to the Topic page and enter identifying information for the new Topic, then click Done.

4.6 Uploading a TopicTopics can be created by uploading JRXML files to the proper location in the repository. When a user clicks Create > Ad Hoc Report on the Home page, the list of Topics on the Topics tab is populated from that location.

Domain Topics are a type of Topic created in JasperServer from a Domain; for more information see section 4.5.3, “Creating Topics from Domains,” on page 73. Regular Topics are created by administrators using iReport. Typically, a Topic is an empty report, that, when associated with a data source in JasperServer, can be used as a Topic in the Ad Hoc Editor.

To upload a Topic:1. Log in to JasperServer as an administrator and select View > Repository.2. Locate the folder where Topics are stored. The location of the Topics folder depends on your system configuration; by

default, Topics are in the Ad Hoc Components > Topics folder.3. Right-click the Topics folder and select Add Resource > JasperServer Report from the context menu.

Figure 4-24 Modifying the Sample Domain Topic in the Edit Domain Topic Wizard

In the Select a Domain drop-down menu on the Data page, you can choose a different Domain for the Topic. If you select a different Domain, all the selections that you made with the current Domain are lost when you click Choose Data.

Use caution when editing Domain Topics that may have been used to create reports. Users who relied on the Domain Topic might receive unexpected data or errors. It is safer to save your changes as a new Domain Topic.

76


The Report Wizard appears, starting with the Naming page.4. Give the Topic a name, a label, and an optional description, then click Next.

The Name field is the internal ID of the object, such as example_topic.The Label field is the visible name of the file in the repository, such as Example Topic.The Description field helps users know what the file is, such as Topic uploaded for User Guide example.

5. On the Main JRXML page, click Browse to upload the topic from the file system.In this example, the file is <js-install>/samples/adhoc/topics/adhoc_sample.jrxml.

6. When the upload is finished, click Next. On the Resources List page, click Next again.Because this is a simple Topic without parameters, there are no resources associated with this Topic. If your Topic has a parametrized query, you can create input controls for it. See 5.2.10, “Completing the Complex Report Example,” on page 99. Such input controls can appear in the Ad Hoc Editor and when the report is run.

7. On the Locate Data Source page, select the radio button next to From the Repository, then select the data source named datasources/JServerJdbcDS from the drop-down list.Topics must be associated with the data source that they were designed for.

8. Click Finish. The Topic appears in the repository.Topics usually do not need a query or customization, but it is possible to define them.

9. On the Validate page, click Save to create the Topic in the repository.

When you select Create > Ad Hoc Report, the Example Topic appears on the Topics tab. If you select it, you can create a report based on the database columns it contains and the data source selected in step 7.

When you create a JRXML file that will be used as a Topic, you can specify the name to display for each field that the Topic returns. To do so, define a field property named adhoc.display for each field declared in the JRXML. The adhoc.display field property should have the following syntax:

<property name="adhoc.display" value="Any Name"/>

For example, this JRXML code declares a StoreState field that will be displayed in reports as Store State:

Topics also support the $R expressions for field names; for more information, see 5.2.12, “Localizing JRXML Reports,” on page 101.

Figure 4-25 Topics Folder on the Search page

<field name="StoreState" class="java.lang.String">

<property name="adhoc.display" value="Store State"/>

</field>

77


4.7 Configuring System-level Ad Hoc OptionsSystem administrators (users with ROLE_SUPERUSER) can control how JasperServer handles the data for Ad Hoc reports.

4.7.1 Limits on QueriesThere is a limit on the number of rows that a report run from the Ad Hoc Editor can contain. There is also a limit on the length of time that a report can take to complete. The limits are defined in configuration parameters set by the system administrator.

Row Limit. When the Ad Hoc Editor starts, it sends a query to the current data source to fetch data. JasperServer limits the number of rows that it fetches:

If the row limit is reached when starting the Ad Hoc Editor, the editor starts but it displays a warning message about the number of rows being returned. If a filter is in effect, you might be able to reduce the number of rows by changing the filter values.If the limit is reached when running an Ad Hoc report, the report stops and a message about the row limit appears. You can redefine the report so that it fetches fewer rows.

Time Limit. When an Ad Hoc report with complicated queries runs, it may take a long time to start returning data. If any one query reaches the time limit before returning data, the query and the report are cancelled. You can redefine the report so that the query completes more quickly, change the limit.

In all cases, you can also ask the system administrator to raise the limits. For details, see the JasperServer Administrator Guide.

4.7.2 Data PoliciesData policies control whether certain processing occurs in JasperServer or in the application storing your data source. These settings apply to reports created or re-saved in the Ad Hoc Editor (that is, changing the settings does not retroactively affect existing reports).

By default, JasperServer relies on the database to group, sort, and aggregate data returned by queries based on Domains when this is feasible. It also limits the data it retrieves to the fields that appear in the report. For JDBC data sources, and for non-Domain, non-JDBC data sources, JasperServer processes the data in memory by default.

Your system administrator can configure JasperServer to handle Domain-based and JDBC-based Ad Hoc reports differently:For Domain-based reports, JasperServer can be configured to process the data in memory, instead. Consider factors such as the number of users and report complexity when deciding how JasperServer should process data for Ad Hoc reports based on Domains data sources.For JDBC-based reports, JasperServer can be configured to push the processing down to the database, as is done by default for Ad Hoc reports based on Domains.

These data policies are controlled on the Ad Hoc Options page. For more information, refer to the JasperServer Administrator Guide.

78

Adding Reports Directly to the Repository

5 ADDING REPORTS DIRECTLY TO THE REPOSITORY

While the Ad Hoc Editor allows end-users to create reports from pre-defined Topics and Domains, you can create reports outside of JasperServer and add them to the repository. You can add these reports in two ways:

From within JasperServer, upload a JRXML file to the repository, along with any other resources the report needs. When you upload the report, a wizard guides you through each step. From iReport, define the report and use the iReport JasperServer plug-in to upload it.

This section gives both a simple and a complex example of uploading a report using JasperServer’s wizard, as well as a discussion of using the using iReport plug-in for JasperServer.

This chapter contains the following sections:Overview of a Report UnitAdding Report Units from JRXML FilesEditing JRXML Report UnitsUsing the JasperServer Plug-in for iReport

79


5.1 Overview of a Report UnitIn JasperServer, a report unit is the collection of elements required to retrieve data and format output. The following figure shows how the various elements contribute to the report output.

The data source and query retrieve data for the report, the main JRXML determines the layout, and input controls and various resources contribute to the output as needed.

The main JRXML file is the core of the report unit. It can either define the other elements internally or refer to existing ones elsewhere in the repository. In this case, the main JRXML uses the repo: syntax to refer to the other elements.

5.2 Adding Report Units from JRXML FilesThis section presents two examples, one simple and one more complex, that illustrate many aspects of uploading JRXML files to create a report unit. Each example is split into several sub-sections, one for each of the different kind of element in the report unit. Each sub-section can be referenced individually when adding your own reports with different combinations of elements.

5.2.1 Simple Report ExampleTo create the simple report in this example, you need access to the <js-install>/samples/reports/AllAccounts.jrxml and the <js-install>/samples/image/logo.jpg files on the JasperServer host. You also need the sample data installed with JasperServer. This simple report has file resources but no input controls. The simple example also includes a custom query to demonstrate how a report unit can modify the JRXML report it is based upon.

5.2.2 Uploading the Main JRXMLThe first tasks when creating a report unit is to give it a name in the repository and then upload the main JRXML file that references all other elements.

Figure 5-1 Elements of a Report Unit

Data Source

Main JRXMLInput Controls

Query

Resources *

ReportData

ReportOutput

* Images, fonts, resource bundles, and scriptlets

ReferencesData Flow

80


To upload the main JRXML for the simple report example:1. Log in to JasperServer as an administrator and select View > Repository.2. Locate the folder where you want to add the report.

In this example, go to Organization > Reports > Samples.3. Right-click the Samples folder and select Add Resource > JasperServer Report from the context menu.

The Report Wizard opens to the Naming page:

4. Enter the following properties for the new report:Name – ID of the report object in the repository, in this example new_simple_report.Label – Display name of the report in the repository, in this example New Simple Report.Description – Optional description, in this example This is a simple example. The description is displayed in the repository and on the View > Reports page to help users determine the contents of the report.

5. Click Next to begin specifying the components of the report. The Report Wizard continues to the Main JRXML page:

6. The main JRXML file is the report you have created in another editor such as iReport. You can either upload a new JRXML file or create a new report based on a JRXML file you have previously uploaded. On the Main JRXML page, select From File System and click Browse to locate the file <js-install>samples/reports/AllAccounts.jrxml.

7. Click Next.JasperServer uploads the main JRXML file, and the Report Wizard displays the list of suggested resources.

5.2.3 Uploading Suggested File ResourcesWhen JasperServer uploads the main JRXML file, it processes the file to create a list of the resources that are referenced in the JRXML. The Report Wizard displays the list of suggested resources on the Resources List page so you can add them to the report unit.

If your report does not reference any file resources, you can skip to section 5.2.4, “Defining the Data Source,” on page 83.

Figure 5-2 Entering the Report Properties on the Naming Page of the Report Wizard

Figure 5-3 Locating the Report on the Main JRXML Page of the Report Wizard

81


To upload the suggested file resources for the simple report example:8. Review the resource names on the Resources List page of the Report Wizard. In this example, there are two images

needed in the report. The resources list shows their name and has a link to add them to the report unit.

9. For LogoLink, click Add Now.The File Resource page appears.

File resources referenced in the main JRXML can either be chosen among existing images in the repository or be uploaded from a file. In either case, you can associate any image file you choose with the resource ID in the main JRXML.

10. The first image in this example is found in the sample data that was created in the repository. Click From the Repository and select images/JRLogo from the drop-down.

11. Click Next.The file resource within the report unit has name, label, and description properties. These are visible only within the report unit, they do not redefine the properties on the repository object that was referenced. The Name field must match the resource name referenced in the main JRXML, which it does by default.

12. Accept the default property values for the image resource by clicking Next.The Resources List page appears again and shows that the LogoLink resource was added.

Figure 5-4 Suggested Resources on the Resources List Page of the Report Wizard

Figure 5-5 Selecting a Resource From the Repository on the File Resource Page

Figure 5-6 Properties of a Resource From the Repository on the File Resource Page

82


13. For AllAccounts_Res2, click Add Now on the Resources List page of the Report Wizard. The File Resource page appears again to locate the second image:

14. For the second image resource, click Upload From File System and browse to the file<js-install>/samples/images/logo.jpg.

15. Click Next.JasperServer uploads the file, and the Report Wizard displays the properties page for the file resource

16. Accept the default naming of the image by clicking Next.The Report Wizard returns to the Resources List page where it shows that all resources referenced in the main JRXML have been added:

17. Click Next to proceed to the Data Source page.

5.2.4 Defining the Data SourceData sources belong to the report engine, in this case JasperServer, and cannot be defined in the main JRXML. Therefore, in the process of creating a report unit, you must define a data sources in JasperServer that the report can use. The Data Source page of the Report Wizard lets you choose the data source in the repository or define a new data source on-the-fly.

Figure 5-7 Uploading a Resource From the File System on the File Resource Page

Figure 5-8 Properties of an Uploaded Resource on the File Resource Page

Figure 5-9 Suggested Resources Added to the Simple Report on the Resources List Page

83


To define the data source for the simple report example:18. Proceed to the Locate Data Source page of the Report Wizard:

The three choices for the data source are:From the Repository – Select an existing data source from the repository.Locally Defined – Lets you define a new data source that will only be available within the report unit.None – Lets you select or define the data source at a later time. You will see an error if you run the report in this state.

19. In this example, select From the Repository and choose /datasources/JServerJNDIDS that is created as part of the sample data in JasperServer.

20. Click Next to proceed to the Query page.

5.2.5 Defining the QueryThe query in report unit determines what data will be retrieved from a data source. The main JRXML may contain a query, but the Report Wizard also allows you to define a new query for the report unit. This allows you to create several different reports from the same JRXML file; the reports will look the same, but their data will be different. The simple report example defines a custom query that displays accounts from a single country.

To define a custom query for the simple report example:21. Proceed to the Locate Query page of the Report Wizard:

The three choices for the query are:From the Repository – Select an existing query object previously defined and stored in the repository.Locally Defined – Lets you define a new query that will only be available within the report unit.None – Uses the query defined within the main JRXML, if any. If there is no query in the main JRXML, you will see an error when trying to run the report.

22. The AllAccounts.jrxml file uploaded in section 5.2.2, “Uploading the Main JRXML,” on page 80 already contains a query. This example overrides the existing query by defining a new query in the report unit.On the Locate Query page, select Locally Defined and click Next.

Figure 5-10 Locate Data Source Page of the Report Wizard

Figure 5-11 Locate Query Page of the Report Wizard

84


The Query page appears where you can enter the properties for you local query:

The locally defined query and its properties are visible only within the report unit.23. In this example, we create a query that retrieves only Canadian accounts. Enter the following properties for the example:

Name – CanadaAccounts.Label – CanadaAccounts.Description – Query for New Simple Report in User Guide.

24. Click Next. The Query Locate Data Source page appears:

When specifying a local query for the report unit, the Report Wizard gives you the opportunity to select a data source that overrides the one associated with the report unit. As with the default data source, you can select one from the repository or define a new one. Selecting None uses the default data source that you selected in section 5.2.4, “Defining the Data Source,” on page 83.

25. Select None to use the report unit’s existing data source, then click Next. The Edit Query page appears:

26. Select SQL in the Query Language field and enter the following Query String to retrieve only Canadian accounts: SELECT * FROM accounts WHERE billing_address_country = "Canada" ORDER BY billing_address_city

Figure 5-12 Entering Properties of a Locally Defined Query on the Query Page

Figure 5-13 Selecting a Query Data Source on the Locate Data Source Page

Figure 5-14 Entering a Locally Defined Query on the Edit Query Page

85


5.2.6 Validating the New Report UnitYou may click Finish anytime in the Report Wizard to skip pages you do not need. The report wizard validates all the elements of the report unit when done, and saves the new report unit in the repository with the type Report. It’s always a good idea to test the report and review the output.

To validate the report unit of the simple report example:27. Click Finish to skip to the end of the wizard.

The Validation page appears automatically, with a message indicating whether the report was successfully validated:

If the report was not validated, you may be prompted to review your entries. Use the left-hand navigation buttons to jump directly to the pages where errors occurred.

28. If the report is valid, click Save. The report appears in the repository with the properties given on the Naming page:

29. Click the name of your new report to run it and view the output. As shown in the figure below, all the accounts listed are in Canada. If you navigate to the last page of the report, you see the two logo images that were referenced as file resources. You could easily change the images in the report by referencing other file resources.

Figure 5-15 Validation Page of the Report Wizard

Figure 5-16 New Simple Report Added to the Repository

86


For more information about running reports, see section 3.1, “Running a Simple Report,” on page 27.

5.2.7 Complex Report ExampleThis section describes the creation of a more complex report with a full set of input controls, as well as a scriptlet class JAR file and resource bundles. To create the report, you must have access to all its resources, including the SalesByMonth.jrxml file, the SalesByMonthDetail.jrxml file (the sub-report). The complex report also uses a datatype and an image in the repository that are part of the sample data installed with JasperServer.

This example uses these resources to create a report that behaves just like the SalesByMonth report found in the Reports > Samples folder of the repository. The beginning of the complex example is similar to that of the simple example. For detailed instructions, see sections 5.2.2, “Uploading the Main JRXML,” on page 80 and 5.2.3, “Uploading Suggested File Resources,” on page 81. The following procedure assumes you are familiar with the Report Wizard and how to navigate between its pages.

To upload the main JRXML and suggested resource files for the complex report example:1. Log in to JasperServer as an administrator and select View > Repository.2. Locate the folder where you want to add the report.

In this example, go to Organization > Reports > Samples.3. Right-click the Samples folder and select Add Resource > JasperServer Report from the context menu.4. Enter the following properties for this example on the Naming page:

Name – new_complex_report.Label – New Complex Report.Description – This is a complex example.

5. On the Main JRXML page, select From File System and click Browse to locate the file <js-install>/samples/reports/SalesByMonth.jrxml.The list of suggested resources indicates that you need a sub-report (the SalesByMonthDetail.jrxml file) and a logo image.

6. On the Resource List page, upload the sub-report:a. Click Add Now in the same row as SalesByMonthDetail.b. Select Upload From File System and click Browse to locate the file <js-install>/samples/reports/

SalesByMonthDetail.jrxml.

Figure 5-17 Output of the New Simple Report Showing the Image Resources

It may help if you are very familiar with the SalesByMonth.jrxml file and the resources it requires. The report file and its resources are found in the <js-install>/samples directory.

87


c. On the next page, accept the default report name and label.7. On the Resource List page again, upload the logo image resource:

a. Click Add Now in the same row as Logo.b. Click From the Repository and choose /images/JRLogo.c. On the next page, accept the default name, label, and description.Both suggested resources in the list have been added.

5.2.8 Uploading Undetected File ResourcesThe report wizard cannot detect every type of resource referenced in the main JRXML. You must be aware of other file resources needed in your report and upload them from the Resources List page. In addition, you must know how they are referenced and give your file resources exactly the same name so they can be associated.

The complex report example needs a scriptlet JAR and two language bundles (Java properties files).

To upload the undetected file resources for the complex report example:8. Add and upload the scriptlet JAR file with the following steps:

a. On the Resource List page, click Add Resource.b. Select Upload from File System and click Browse to locate the <js-install>/samples/jars/scriptlet.jar file. c. The next page indicates that the file was successfully loaded and automatically detected as a JAR. Enter the following

information; the name is referenced in the main JRXML file, so you must enter it exactly as shown:Name – Scriptlet.Label – Scriptlet JAR.Description – Scriptlet JAR for complex example.

9. Add and upload the English resource bundle with the following steps:a. On the Resource List page, click Add Resource again.

Figure 5-18 Suggested Resources Added to the Complex Report on the Resources List Page

When you upload a TrueType font as a resource, the file must have the .TTF file extension.

Figure 5-19 Adding the Scriptlet JAR on the File Resource Pages

88


b. Select Upload from File System and click Browse to locate the <js-install>/samples/resource_bundles/sales.properties file.

c. The next page indicates that the file was successfully loaded and automatically detected as a resource bundle (a Java properties file). Enter the following information; the Name field must be exactly as shown:

Name – sales.properties.Label – sales.properties.Description – Default English resource bundle.

10. Add and upload the Romanian Resource bundle with the following steps:a. On the Resource List page, click Add Resource again.b. Select Upload from File System and click Browse to locate the <js-install>/samples/resource_bundles/

sales_ro.properties file. c. The next page indicates that the file was successfully loaded and automatically detected as a resource bundle (a Java

properties file). Enter the following information; enter the Name field exactly as shown:Name – sales_ro.properties.Label – sales_ro.properties.Description – Romanian resource bundle.

Figure 5-20 Adding the English Resource Bundle on the File Resource Pages

Figure 5-21 Adding the Romanian Resource Bundle on the File Resource Pages

89


When done, all three files appear in the Resources List.

If you wish to upload a different file for a named resource, click the resource name/ID in the table and locate the new file or repository object. You can also change the label and description of the resource, but not its name. If there is a mistake in a resource name/ID, click the X icon in the same row to remove the file resource and add it again.

5.2.9 Adding Input ControlsInput controls are standard graphical widgets that take user input in a pre-determined format and pass it into the report. When a report is designed and configured for input controls, a user can modify runtime selections, such as WHERE filter clauses in SQL parametrized queries. JasperServer displays the input control widgets with the report and regenerates the report when the user changes the input values.

Input controls are complex objects that can be configured in many ways. However, you must create the input controls so that they return the exact type, range, and number of values expected by your report. In general, there are two aspects to defining an input control: the data type (for example number or text) and the widget type (for example text field or radio button) that allows that input.

Boolean – A yes/no value determined by a check box.Single value – A text, number, date or date/time, optionally constrained by a minimum value, maximum value, or both. Text input can also be constrained by a matching pattern. Single values provide a text box for the user to enter a value, but date and date/time also provide a calendar icon.Choice of multiple values – The choices offered to the user can either be a static list of values that you specify or a dynamic list of values returned by a separate query. Once the list of values is determined, the widget type can be:

Drop-down list to select a single value.Radio buttons to select a single value.Multi-select list to select multiple values.Check boxes to select multiple values.

All choices are presented and selected by their text representation, but the report may process the input value, for example to interpret a string of digits as a number.

The query in the SalesByMonth.jrxml file of the complex example has several parameters that require input controls. Each input control is a different type to demonstrate how each can be added to the report unit. As with other elements of a report unit, input controls and the data types they rely on can either be locally defined or reused from the repository. Most components in the example are defined locally to demonstrate the use of the report wizard.

5.2.9.1 Adding a Text Input Control

The most straightforward input control is a text box that allows the user to enter a value. In this example, the data type for the value is a number, meaning that JasperServer will verify that the user input is numeric.

Figure 5-22 Undetected File Resources Added on the Resources List Page

You must define an input control even when parameters have default values. To prevent users from changing the default, you can make the input control read-only or invisible.

90


To add a text input control to the complex report example: 11. On the Resource List page of the report wizard, click Add Control.

The Locate Input Control page appears.

12. If you have created input controls for similar reports, you can reuse them if they have the same parameter name in the report. Also, you must create the input control in the repository, you cannot reuse input controls that you defined locally in another report.For this example, select Locally Defined.

13. On the next page, enter the naming properties for the input control as well as the type of the input:

The name is referenced in the main JRXML file, so you must enter it exactly as shown:Parameter Name – The name of the parameter in the report that receives the user value, in this example TextInput.Prompt Text – The label that the user sees next to the widget for this input, in this example Text Input Control.Description – An optional description that only appears within the report wizard.Type – Determines the type of the input control, in this example Single Value.Mandatory, Read-only, Visible – Affect how the input control is displayed, in this example use the default settings.

14. On the next page, you can locate a datatype already stored in the repository. Data types can be simple definitions of the expected input (numbers, text, date, or date/time), but the they can also include range restrictions that JasperServer will enforce. If you have a data type saved in the repository that you want to reuse, make sure its type and range are compatible with the input control you want.For this example, select Locally Defined:

Figure 5-23 Locate Input Control Page of the Report Wizard

Figure 5-24 Entering the Properties of the Text Input Control

Figure 5-25 Locating the Datatype for the Text Input Control

91


15. On the next page, enter the properties for the locally defined datatype associated with the input control:

The name and label are required, but they are visible only when defining the input control:Name – integer_type.Label – Integer Control.Description – An optional description that only appears within the report wizard; leave blank in this example.Type – Determines the format of the data that the user may enter, in this example choose Number.

Minimum value and Is strict minimum – The lower bound of the value the user may enter; a strict minimum means the value itself is not allowed. Leave blank in this example.Maximum value and Is strict maximum – The upper bound of the value the user may enter; a strict maximum means the value itself is not allowed. Leave blank in this example.

16. Click Save.The Resources List page appears with the new TextInput control in the list of resources.

5.2.9.2 Adding a Simple Check Box Input Control

A simple check box provides a true/false (boolean) input that can be used to conditionalize some part of the report.

To add a simple check box input control to the complex report example: 17. On the Resource List page of the report wizard, click Add Control.18. On the Locate Input Control page, select Locally Defined.

Figure 5-26 Defining the Properties of the Datatype for Text Input

The number format allows users to enter both integers and decimals. Your report must handle both kinds of values when processing the parameter that receives the number.

Figure 5-27 Added Controls in the Resources List of the Report Wizard

92



The name is referenced in the main JRXML file, so you must enter it exactly as shown:Parameter Name – CheckboxInput in this example.Prompt Text – The label for the input control is usually formulated as a question, but use Checkbox Input Control in this example.Description – Leave blank in this example.Type – Boolean in this example.Mandatory, Read-only, Visible – Use the default settings in this example.

20. Click Next. The Resources List page appears with the new CheckboxInput control.

5.2.9.3 Adding a Drop-Down Input Control

Another type of input control gives the user a pre-determined list of choices to select from. The design of the report determines whether you must create a single-select or multi-select list. When creating the input controls you can select whether to present a single choice as a drop down list or a set of radio buttons. Multi-select controls can either be a multi-select list or a set of check boxes. Radio buttons and check boxes are usually appropriate if there are few choices, usually five or less. This example only has three pre-determined but uses a drop-down list.

The predetermined choices are defined in a list of values object. You can either create one locally for the input control or reuse one that you have created beforehand in the repository.

To add a drop-down input control to the complex report example: 21. On the Resource List page of the report wizard, click Add Control.22. On the Locate Input Control page, select Locally Defined.23. On the next page, enter the naming properties for the input control as well as the type of the input:

The name is referenced in the main JRXML file, so you must enter it exactly as shown:

Figure 5-28 Entering the Properties of the Check Box Input Control

Figure 5-29 Entering the Properties of the List Input Control

93


Parameter Name – ListInput in this example.Prompt Text – List Input Control in this example.Description – Leave blank in this example.Type – Single-select List of Values in this example.Mandatory, Read-only, Visible – Use the default settings in this example.

24. On the next page, you can locate a list of values already stored in the repository. If you have a list of values saved in the repository that you want to reuse, make sure its values are compatible with the parameter that receives this input.For this example, select Locally Defined:

25. On the next page, enter a name, label, and optional description for the locally defined list of values. These properties are not visible outside of the input control:

Enter the following values:Name – list_type in this example.Label – List Type in this example.Description – Leave blank in this example.

26. On the next page, enter the values that the user will choose from. Each value has a label that is displayed instead of the actual value. The value itself is passed to the report, so you must ensure that its type and value match what is expected.

For each value that you want to add to the list, enter its label and its value, then click +. If you make a mistake, check the box in the row you want to remove and click –. The label for every item must be unique. For this example, enter:

Label First Item with value 1.Label Second Item with value 2.Label Third Item with value 3.

27. Click Save.The Resources List page appears with the new ListInput control.

Figure 5-30 Locating the List Type for the List Input Control

Figure 5-31 Defining the Naming Properties of the List of Values

Figure 5-32 Defining the Values of the List of Values

94


5.2.9.4 Adding a Date Input Control

In this example of adding a date input control, we use a data type that already exists in the sample data in the repository:

To add a date input control to the complex report example: 28. On the Resource List page of the report wizard, click Add Control.29. On the Locate Input Control page, select Locally Defined.30. On the next page, enter the naming properties for the input control as well as the type of the input:

The name is referenced in the main JRXML file, so you must enter it exactly as shown:Parameter Name – DateInput in this example.Prompt Text – Date Input Control in this example.Description – Leave blank in this example.Type – Single Value in this example.Mandatory, Read-only, Visible – Use the default settings in this example.

31. On the next page, select From the Repository. The drop-down automatically shows the data datatypes found in the repository. Select /datatypes/date from the drop-down:

32. Click Next.

The Resources List page appears with the new DateInput control.

5.2.9.5 Adding a Query-Based Input Control

This last example of an input control shows how the choices available to the user can be dynamically based on your data. JasperServer performs a query whose results are used to create the list of choices. You must configure the query and designate how the results are displayed in the input control, as well as what value is passed as the corresponding parameter.

To add a query-based input control to the complex report example: 33. On the Resource List page of the report wizard, click Add Control.34. On the Locate Input Control page, select Locally Defined.

Figure 5-33 Entering the Properties of the Date Input Control

Figure 5-34 Locating the Datatype for the Date Input Control

95



The name is referenced in the main JRXML file, so you must enter it exactly as shown:Parameter Name – QueryInput in this example.Prompt Text – Query Input Control in this example.Description – Leave blank in this example.Type – Single-select Query in this example.Mandatory, Read-only, Visible – Use the default settings in this example.

36. For a query-based input control, you can use a query stored in the repository. In this example, we define a query that is local to the input control, with its own properties and query string.On the Locate Query page, select Locally Defined.

37. On the next page, enter naming properties for the local query. For this example, enter testQuery in both the Name and Label fields.

Figure 5-35 Entering the Properties of the Query Input Control

Figure 5-36 Locating the Query for the Query Input Control

Figure 5-37 Defining the Properties of the Query for the Query Input Control

96


38. On the Locate Data Source page, select None to use the same data source you defined for the report. In your own reports, you can select a different data source from the repository or define one that is local to the input control.

39. On the Edit Query page, define the query that retrieves both the labels and the values to be displayed by this input control. In this example, keep the default value in the Query Language field, and enter the following Query String:SELECT user_name, first_name, last_name FROM users

40. For each row in the results of the query, JasperServer will display one choice in the widget you chose as the input type (drop-down, radio buttons, mutli-choice, check boxes). On the Query Information page, name the database column that will be used as the input value and those that will be presented to the user. The column names must match those in the SELECT clause of the query string exactly.For each column that you want to display in a choice, enter its name, then click +. If you make a mistake, check the box in the row you want to remove and click –.

For this example, enter the following column names:Value Column Enter – user_name. Visible Columns – first_name and last_name.

41. Click Save.The Resource List page displays all the resources, including the new input controls.

Figure 5-38 Locating the Data Source for the Query Input Control

Figure 5-39 Editing the Query String for the Query Input Control

Figure 5-40 Selecting Columns for the Query Input Control

97


5.2.9.6 Configuring the Display of Input Controls

To complete the configuration of input controls, enter the optional settings at the bottom of the Resources List page.

To configure the display of input controls in the complex report example:42. The following settings appear whenever one or more input controls are defined. They apply to all input controls

simultaneously:The Controls Layout specifies where the input controls should appear. This example uses the default pop-up window, but you can also make the input controls appear in a separate browser window or at the top the report itself.Check Always Prompt to force JasperServer to prompt the user even though none of the input controls are mandatory.Leave the field Optional JSP location blank for this example. This setting allows you to specify a different JSP file to change to appearance of the input controls.

5.2.9.7 About Cascading Input Controls

JasperServer JRXML-based reports can include input controls whose values are determined by user's selection in other input controls. For example, consider a report that has input controls for country, state, and city. By leveraging the cascading functionality, the options in the State input control are determined by the value selected in the Country input control. When the user selects a state, the list of values includes only those in the selected state. These cascading input controls use queries to determine the values to display in each input control field.

The goal is to use input controls as parameters for a query that populates another input control. To do so, the input control's query must use a special syntax to reference a parameter name. The syntax is identical to the JasperReports syntax used in report queries. For example, a parameter is referenced using the following convention:

Consider an example report that returns data identified by country and city. It includes input controls called COUNTRY and CITY. The query used by the CITY input control retrieves city names from a table called accounts based on the value selected by the COUNTRY input control, for example:

When the user selects a country from the COUNTRY input control, the value selected is used by the query of the CITY input control; the CITY input control is refreshed to show the result. Note that there are other ways to use a parameter in a query.

For an example of running a report with cascading input controls, see section 3.3.2, “Cascading Input Controls,” on page 33.

Figure 5-41 All Added Controls on the Resources List Page

$P{parameter name}

select city from accounts where country = $P{COUNTRY}

98


5.2.10 Completing the Complex Report Example

To finish the complex report example and validate it:43. On the Locate Data Source page, select From the Repository and choose /datasources/JServerJNDIDS from the drop-

down.44. Click Finish to skip to the end of the wizard.

Skipping the last steps of the wizard accepts the default values for those options.The Validation page displays a message indicating whether the report was successfully validated.

45. If the report was validated, click Save.

The report appears in the repository.

46. Click the display name of your new report to run the report and view it.The pop-up dialog appears with all of the input controls you defined. Enter sample values as shown in left-hand figure below. The left-hand figure also shows all the dynamic choices for the Query Input Control:

If the report was not validated, you may be prompted to review your entries. Make corrections and try to validate the report again.

Figure 5-42 New Complex Report Added to the Repository

Figure 5-43 Entering Input Controls When Running the New Complex Report

99


47. Click OK or Apply to run the report with the selected input. JasperServer enforces the proper format defined for each input control. The Text Input Control is defined as a numeric type and only accepts valid numbers, as shown in the right-hand figure. Enter a number and click OK or Apply again.

48. The sample report includes a header that displays the value of each parameter received from the input controls.

You can open the Report Options widow at any time from the report by clicking the icon. Clicking OK closes the Report Options window; clicking Apply keeps it open to easily change values and run the report again.

5.2.11 More about DatatypesA datatype in JasperServer is more than just a classification of the data. It also includes validation criteria. The datatype description page contains these fields:

Figure 5-44 Output of the New Complex Report Showing Values from the Input Controls

If running the new report results in an error, edit the report to review your settings. If you cannot identify the problem, edit the SalesByMonth sample report (in the repository at /reports/samples) and compare its settings to those you configured for your new report.

Name The name of the datatype.

Label The label of the datatype.

Description Any additional information you want to provide about the datatype.

Type The actual data type. Possible values are Text, Number, Date, or Date-Time.

Max length The maximum number of characters allowed in the field.

Decimals The number of decimal places allowed in the field.

Pattern A regular expression that restricts the possible values of the field.

Minimum value The lowest permitted value for the field.

Is strict minimum If checked, the minimum value itself is not permitted; only values greater than the minimum value are permitted.

Maximum value The highest permitted value for the field.

Is strict maximum If checked, the maximum value itself is not permitted; only values less than the maximum value are permitted.

100


5.2.12 Localizing JRXML ReportsJRXML reports (including Topics) support the $R expressions for field names; such expressions are used to localize reports into various languages. Each $R expression refers to an entry in a resource bundle properties file that you must create. For example, if we were to localize a field called StoreState, we might use this JRXML:

JasperServer looks for a label with the ID of StoreState. In order for this localization to work properly, you must create the resource bundle with the correct labels, and declare the resource bundle in the header of the JRXML file. For example:

In the above, simpleTable is the name of the resource bundle file that contains the StoreState property. iReport can help you localize your report by creating the resource bundle as well. When you upload the report, you must upload the resource bundle, as well. If you edit a resource bundle in iReport, you can right-click it in repository (using the JasperServer Plug-in) and select Replace with Current File.

5.2.13 Default Fonts in JasperServerBy default, JasperServer uses three fonts you can use in your reports:

DejaVu SansDejaVu SerifDejaVu Sans Mono

Using the DejaVu fonts shipped with JasperServer ensures that the fonts are always available in all environments, which in turn ensures the PDF will be pixel perfect every time.

The DejaVu replace the Java logical fonts used in previous versions of JasperServer:SansSerifSerifMonospaced

When using the DejaVu fonts coming from JasperReports font extensions, you don’t need to set any other font attributes (such as the pdfXXX attributes) in the JRXML, nor do you need to specify font mapping.

All is taken care of in the font extension file that makes these fonts available.

For more information on DejaVu, refer to its SourceForge project at: http://dejavu-fonts.org/wiki/index.php?title=Main_Page.

<field name="StoreState" class="java.lang.String">

<property name="adhoc.display" value="$R{StoreState}"/>

</field>

<jasperReport name="StoreSales" pageWidth="595" pageHeight="842" columnWidth="515" leftMargin="40" rightMargin="40" topMargin="50" bottomMargin="50" resourceBundle="simpleTable">

SansSerif, Serif, Monospaced can still be used, but should be considered deprecated. This is because these Java logical fonts map to different TTF files in different environments, and run the risk of text being cut when exported to PDF, due to font metric mismatches. Also, the java logical fonts listed above aren't recognized by browsers and are substituted with other font families in some browsers. For example, when viewing a report that uses the SansSerif logical font in Firefox in a Windows environment, the font is rendered as Serif.

When you upload a TrueType font to the repository, the filename must include the correct extension (.TTF).

101

http://dejavu-fonts.org/wiki/index.php?title=Main_Page


5.3 Editing JRXML Report UnitsOnce a report unit has been added to the repository, you can go back and edit any of its elements, including the file resources and input controls. This example will modify the display text of the ambiguous Text Input Control.

To edit the complex report example:1. Log in to JasperServer as an administrator and select View > Repository.2. Search or browse the repository to locate the report. In this example, go to Organization > Reports > Samples.3. Right-click the New Complex Report and select Edit from the context menu.4. The report wizard opens with all the settings of the saved report. Navigate to the page of the report wizard where you want

to make changes; in this example click Controls & Resources in the left-hand list.5. You can make modifications in the report wizard, as if you were creating the report unit. For this example:

a. Click the name of the TextInput control.The Locate Input Control page shows that this input control is locally defined.

b. Click Next.The properties page shows the settings for this input control.

c. Change the contents of the Prompt Text field to Enter a number.d. Click Next until you reach the Datatype page where you can click Save.

If desired, you could make changes on these other pages, or even change the data type to one from the repository.In this example, don’t make any changes.

6. On the Resources List page of the report wizard:a. Change the Controls Layout to Top of Page.b. Clear the Always Prompt box.c. Click Finish.

7. When the report has successfully validated, click Save.8. Run the New Complex Report again.

Instead of appearing in a pop-up before the report; the input controls appear above the full report.

In Figure 5-45, you can see the new prompt label for the text input control. Because none of the input controls in this example are required, the report can display with all input controls still blank. Enter values and click Run Report to modify the report output according to your input.

Figure 5-45 Output of the Modified New Complex Report

102


5.4 Using the JasperServer Plug-in for iReportThe JasperServer plug-in for iReport provides report developers with a quick and easy way to access reports inside the JasperServer repository. The plug-in uses the JasperServer web services to interact with the server, and you can connect to multiple servers. This can make it easy to access both test and production environments.

The plug-in offers these features:Repository browsing.Create, modify, and delete folders, generic resources (including images, fonts, JRXML files, JAR files, and property files), reports, datatypes, list of values, and input controls.Create, modify, and import data sources (JDBC, JNDI, and JavaBean).Add, remove, and link controls to reports.Drag and drop images and sub-reports into the design page.Access to Domains through the Domains plug-in for iReport.

This section includes these topics:Connecting to JasperServer from iReportCreating a Report Unit in the Repository from iReportManaging Resources in the Repository from iReportEditing a Report in the Repository from iReportRunning a Report from iReportCreating Reports in iReport Based on a Domain in JasperServerCreating Chart Themes in iReport

5.4.1 Connecting to JasperServer from iReportYou can connect to JasperServer (Professional or Enterprise) directly from iReport.

To access the JasperServer repository within iReport:1. Start iReport. For example, in Windows select Start > Programs > JasperServer Pro > Start iReport on the computer

hosting JasperServer. iReport appears.

2. Open the JasperServer Plug-in for iReport by clicking Window > JasperServer Repository.The Repository Navigator tool bar appears:

This section assumes that you installed iReport when you installed JasperServer. For more information, refer to section 8.2, “iReport Plug-ins,” on page 166.JasperServer supports the version of iReport that ships with it; you cannot necessarily use a version of iReport or JasperReports that has a later version number than the version of JasperServer you use. Jaspersoft keeps the release numbers of compatible versions consistent. For example, Jasper Server 3.7 supports iReport 3.7 and JasperReports 3.7.

103


3. When iReport starts for the first time, no servers are configured. To add a server, click the first button in the repository navigator tool bar.

4. Enter the information that the plug-in will use to access your JasperServer instance. All fields are required:Name – An identifier for this JasperServer instance and its repository in the iReport Repository Navigator.JasperServer URL – Full URL to the repository web service; the default URL is provided and you only need to change the hostname.Organization – If there is more than one organization in the JasperServer instance, you must specify the ID or the alias of the user’s organization, for example organization_1. In the default installation with a single organization, you can leave this field blank.Username – ID of the user account to use when accessing JasperServer. The view of the repository and any actions you take through iReport will use the permissions for this user.Password – Password for the given user.

5. Click Save, then expand the repository tree in the Repository Navigator. The JasperServer repository tree appears as it would to the user in the given organization.You can add any number of servers to this list. If you have multiple versions of the plug-in installed, the list includes all the servers configured for every version iReport (after 3.1) that is installed on this computer. Note that you may experience problems when connecting to servers that are not compatible with your version of the plug-in.

Figure 5-46 Connecting to JasperServer from iReport

104


6. For each server to which you have configured access in the JasperServer Plug-in, you can:Browse the repository by double-clicking the server and folder icons.View the property information of the resources in the repository. Download, edit, and upload JRXML files. Download images and other files by clicking Export File on the Resources tab of the resource’s Properties window.

5.4.2 Creating a Report Unit in the Repository from iReportTo add a new report unit, you need a JRXML file, which you should create in iReport beforehand. A report has a main JRXML file, a data source, a set of input controls (zero or more), and a set of resources (zero or more). To create a report that returns data from a Domain, see section 5.4.6, “Creating Reports in iReport Based on a Domain in JasperServer,” on page 108.

To create a report unit in the repository:1. Right-click the parent folder for the new report and click Add > Report Unit in the context menu.

You are prompted for the main JRXML file.2. Select a JRXML file in the repository or one saved on your hard drive. If you have a report open in the design area, select

Locally Defined and click Get source from current opened report to use it in the new report unit.3. Click Next.

You are prompted for the data source.4. Select a valid data source (either from the repository or locally defined) and click Finish.5. The report unit appears in the repository tree. If it doesn’t, right-click the server name and select Refresh from the context

menu.6. To add an image from the repository to a report, drag the image into the design window from the repository tree.

The iReport plug-in adds the image element for you, setting an expression that refers to the image’s location in the repository.

Figure 5-47 iReport Displaying a Report from the Repository Navigator

105


7. To add a subreport to a report, drag the JRXML for the subreport from the repository into the detail band. The JRXML for the subreport must already be created and saved as a resource in the repository or in the reportA sub-report element is created. If the main report uses a JDBC connection, set the connection expression of the sub-report to $P{REPORT_CONNECTION} in the Properties window’s subreport tab.

8. To run the report, right-click the report unit and select run Report Unit from the context menu. For more information, refer to 5.4.5, “Running a Report from iReport,” on page 108.

5.4.3 Managing Resources in the Repository from iReportWhile creating reports that you intend to store in the JasperServer Repository, you will also need to create and manage the resources associated with them, such as images, JARs, JRXML files, properties files for localized reports, input controls, datatypes, lists of values, style templates (JRTX), and data sources. Or if you are maintaining existing reports, you may need to access, modify, and save changes to existing resources. You can also modify the location, name, or description of the repository folders.

To add, modify, or delete resources to the repository from iReport:

1. To add a resources in the repository navigator, right-click the folder that will hold the resource, select Add then click the desired object in the context menu.

2. To change the location of a resource in the repository, locate the object, then drag-and-drop it to the new location.Alternatively, right-click the object and select Copy or Cut, or use the keyboard shortcuts: Ctrl-C and Ctrl-X, respectively. Locate the destination and right-click and select Paste, or use the keyboard shortcut Control-V. When cutting the object, it will not be removed from its original location until pasted in the new location.

3. To delete a resource from the repository, locate the object, right-click it, and select Delete. You must confirm you action to prevent accidental deletions.

4. To modify a resource, navigate the repository tree to find its folder, then right-click the resource and select Properties. 5. In the dialog window that appear, there are one or more tabs depending on the type of resource. On the General tab, you

can view the object’s repository label and description. If the logged in user has administrative privileges, you can modify the values and save them back to the Repository.

The other tabs, if any, contain controls that are specific to each type of resource. File-based resources have a Resource tab to replace or export the file, and other repository objects have their own specific settings. As shown in the following figure, an image resource shows the image itself, and an input control lets you edit its various parameters:

You cannot run a subreport directly on the server; you must run the whole report unit.

When you upload a report that uses the repo: syntax to refer to resources in the repository, iReport prompts you to locate the resources. Browse the repository to the correct resource and click OK.

Figure 5-48 Editing General Properties of Repository Objects in iReport

106


6. Click Save in the Properties dialog to make your changes effective in the repository.

5.4.4 Editing a Report in the Repository from iReport

In the repository tree, report units appear as special folders with this icon: . They contain JRXML files with this icon: . When working with JRXML files in the Repository from iReport, you must be aware that iReport operates on a copy of the file. You must upload it back to the repository when finished, as explained in the following procedure:

To edit a JRXML file in the Repository from iReport:1. In the repository tree, right-click the JRXML file in the report unit and select Open in Editor.

The JRXML is extracted from the repository and stored as a local copy in the <USER_HOME>/.ireport/jstmp directory. This directory is never automatically cleared out.The JRXML appears in the Designer window.

2. Edit the file as needed, either in the Designer or in the XML editor. See section 5.4.2, “Creating a Report Unit in the Repository from iReport,” on page 105 for instructions on adding images or subreports to your JRXML file.

3. To save the file and upload it to the repository, right-click it in the repository tree and click Replace with Current JRXML. A message confirms the operation’s success.

To edit a Report Unit in the Repository from iReport:1. In the repository tree, right-click the report unit and select Properties.2. On the General tab, change the repository name or description as appropriate.3. On the Main Report and Data Source tab, you can change the JRXML file for the report, either by selecting one from the

repository, or uploading one through iReport. Click Current Report to use the JRXML currently being edited in iReport. Similarly, you can select the data source from the repository or from iReport. See Figure 5-50 on page 108.

4. On the Other tab, you can set display properties for any input controls. The JSP fields are for modifying the appearance of the controls, and the Controls Layout determine where they appear.

Figure 5-49 Editing Resource-Specific Properties of Repository Objects in iReport

107


5. Click Save Report Unit in the Properties window to make the changes effective in the JasperServer repository.

5.4.5 Running a Report from iReport

To run a report on the server using all the export options set in iReport:1. Right-click a report in the repository tree and click Run Report Unit. 2. If the report has input controls, the Report Parameters window prompts you for values.

The report is displayed in the Report Viewer Window. If the report does not display, look for errors or messages in the Report Problems Window at the bottom of the iReport interface.

5.4.6 Creating Reports in iReport Based on a Domain in JasperServerA Domain is a virtual view of a data source that represents the data in business terms appropriate to your audience, and it limits the data to that which is appropriate for the audience. For more information about Domains, see chapter 6, “Creating Domains,” on page 115.

The Domain plug-in enables iReport users to generate reports from Domains. The plug-in is installed in iReport by default. It relies on the JasperServer plug-in to access the repository.

Figure 5-50 Editing Parameters of a Report Unit in iReport

Figure 5-51 Report Parameters Window in iReport

108


To create a report in iReport based on a Domain in JasperServer:1. Configure iReport to access your JasperServer repository as described in section 5.4.1, “Connecting to JasperServer

from iReport,” on page 103.2. Click Window > Domains.

The Domain Window appears docked on the left-hand side of the screen.

3. To start a report based on a Domain, click File > New > Domain Report.The Domain Report wizard opens to the Connection step:

4. Select a JasperServer connection to determine the server and repository containing the Domain you want, then click Next.

Figure 5-52 Domains Window in iReport

Figure 5-53 Connection Step in the iReport Domain Report Wizard

Figure 5-54 Domain Step in the iReport Domain Report Wizard

109


The Domain step displays a selector containing all the Domains within the repository visible to the user defined in the connection. If the user’s organization includes sub-organization, the list will include any Domains they define as well.

5. Select a Domain and click Next.

The Filters step displays the Domain’s items, which may correspond to fields and calculated fields in the Domain.6. Define any necessary filter conditions on the fields of the Domain. Even if that field is not included in the report, the filter

will be active and will apply to the rows of data that will appear. Filters will limit the data your report will return, and you may select any field to prompt the user with an input control. This dialog is similar to the Filters page in the Choose Ad Hoc Data wizard within JasperServer. For more information, see section 4.5.2.2, “The Filters Page,” on page 71.

7. Click Next and specify a name and a location on your hard drive to save the report.

The Name and Location step determines the file name of your report in iReport, not in the JasperServer Repository. See below to publish your report in the repository.

8. Click Finish.The report document appears in design area. The Domain Window now shows the sets and items in the Domain.

Figure 5-55 Filters Step in the iReport Domain Report Wizard

Figure 5-56 Name and Location Step in the iReport Domain Report Wizard

110


9. To add items from the Domain, drag them to the detail area of the JRXML in the designer. Edit your report to format its data and look and feel.

If you want to change the filters on the Domain data, click Edit Filters in the Domains Window. Filters are defined as queryFilterString elements in the XML of the report. Click XML next to Designer to view the XML. For the simple filter shown in step 6, the generated XML is the following:

The query has two elements: queryFields and queryFilterString:Field IDs in both elements are specified as set_ID.field_ID. The filter uses the Domain Expression Language described in section 7.2, “The DomEL Syntax,” on page 150.

10. When you are satisfied with the report, save your report, then click Publish Report in the Domain window.You are prompted for a name, label, and description of the new report unit.

11. Enter a name (object ID), label (display name) and an optional description for the report in the repository, then click Next.You are prompted for location for the report unit.

12. Select a valid repository location and click Finish.13. If the report doesn’t appear in the repository tree, right-click the server name and click Refresh.14. With the report published to the server, you can test it by clicking in the repository navigator window.

The report output appears in the Report Viewer Window.

Figure 5-57 Designing a Report in iReport Based on a Domain in JasperServer

<queryString language="sl"><![CDATA[<query>

<queryFields><queryField id="newSet2.amount"/>

</queryFields><queryFilterString>newSet2.amount >= 10000</queryFilterString>

</query>]]></queryString>

You cannot run a Domain report until it has been published to JasperServer.

111


5.4.7 Creating Chart Themes in iReportUsing iReport, you can create new chart themes that give a custom look to any chart. You can easily set the fonts, colors, line widths, and other settings that determine the appearance of charts. You can then import the chart theme for use in reports generated in JasperServer, either on a report-by-report basis or as a global setting for all charts that do not provide their own theme.

To create a new chart theme in iReport:1. Select File > New > Chart Theme.

The new file dialog opens with a default file name. Chart themes use the .jrctx file extension.

2. Enter a name and location and click Finish.Alternately, open an existing chart theme file with the .jrctx extension.The chart theme editor appears in the Designer window.

3. Use the following panes to work with your chart theme:Template inspector on the left . Contains the categories of properties that can be modified.Chart properties on the right. Lists the properties in each category and lets you modify their settings.

These panes are shown in Figure 5-59 on page 113.The available options are based on the JFreeChart library used to generate charts. Note that iReport only supports the most common options provided by JFreeCharts.

4. Select each category in the template inspector and review the available option, which appear in the properties pane to the right.

5. Select a property to change its value. Depending on the nature of the property, you might type text, select a color, check or clear a check box, or select a value from a dropdown.As you update the chart theme, the Designer shows your changes. For example, change the Series Color property in the Plot category to set the color of the data series in the chart.Selector different chart types from the dropdown at above the Designer to see how the theme appears with different types of charts. This is especially important if you are creating a theme that will be used with many reports, such as a corporate chart theme.To view the XML that defines the chart theme’s appearance, click XML above the Designer.

Figure 5-58 New Chart Theme in iReport

112


6. When you are satisfied with the chart theme, click File > Save to save your chart theme.This saves the report to your local hard drive.

7. In the template inspector, right-click Chart Theme and click Export as Jar from the context menu.

You are prompted to identify the chart theme.8. Enter the name of the theme and the name of the JAR file.

The chart theme name is the text that appears in the Chart Theme dropdown in iReport’s properties pane.9. If you don’t want this theme to be available in iReport for some reason, clear the check box. 10. Leave the box checked if you want the JAR to be placed on iReport’s classpath.11. Click Export.

The chart theme is exported. It can be used at the report or server level in JasperServer. For more information, refer to the JasperServer Administrator Guide.

Figure 5-59 Chart Theme Editor in iReport

Figure 5-60 Exporting a Chart Theme

In iReport, you can upload the chart theme to JasperServer using the JasperServer plug-in; right-click the folder in the repository where the theme should reside, and select Add > JAR Archive.

113


114

Creating Domains

6 CREATING DOMAINS

A Domain is a metadata layer that provides a business view of the data accessed through a data source. It presents the data in business terms appropriate to your audience, and it can limit the access to data based on the security permissions of the person running the report. A Domain defined in JasperServer and can be used to create reports, Ad Hoc reports, and Domain Topics.

This chapter covers the process of creating Domains and defining their contents. For instructions on creating Domain Topics and reports based on Domains in the Ad Hoc Editor, see section 4.5, “Creating a Report from a Domain,” on page 67. Domains defined in JasperServer can be accessed through iReport as well, as described in section 5.4.6, “Creating Reports in iReport Based on a Domain in JasperServer,” on page 108.

This chapter contains the following sections:Introduction to DomainsExample of Creating a DomainUsing the Add New Domain DialogUsing the Domain DesignerEditing a Domain

6.1 Introduction to DomainsProduction databases typically contain data in tables that are optimized for storage and retrieval. Columns with data relevant to users need to be joined across several tables, filtered by business needs, secured against unauthorized access, and labeled with user-friendly names. In relational databases, a view can perform some of these functions. In JasperServer, a Domain performs all these functions and more such as the localization of report text and permissions based on data values.

A Domain is a virtual view created and stored in JasperServer, without modifying the data source. Through a Domain, users see columnss that have been joined, filtered and labeled for their business needs, and the data values they can access are limited by security policies. Administrators define Domains, and users create reports based on the Domains using either the Ad Hoc Editor or iReport.

Domains are similar to Topics in that they are used in the Ad Hoc Editor as a basis for designing reports. They are different from Topics in several significant ways:

Domains can be created directly through the JasperServer user interface.

Typically, Domains are created for end users by database administrators or business analysts who understand the structure of the raw data in the database. In the default JasperServer installation, those who create Domains must have organization admin privileges.

115


Domain creators can write SQL queries, joins, filter expressions and security files to specify exactly what data can be accessed, as well as labels and locale bundles to specify how the data appears.When designing a report based on a Domain, JasperServer can optimize database access to allow editing of reports that access huge datasets.Report creators have the opportunity to further filter data and prompt for user input later when running the report.

This last point is a very powerful feature of Domains. Administrators create Domains, but when users create a report based on a Domain, they have to opportunity to further choose the data from within the Domain. Users can select a subset of columns to appear in the Ad Hoc Editor and give them custom labels. Users can filter the data for each column, and more importantly create input controls on columns so that report readers can modify the filter values.

Once all these settings have been made, users can save the report for others to run, and also save the settings in a Domain Topic so others can design similar reports. For more information, see sections 4.5, “Creating a Report from a Domain,” on page 67 and 4.5.3, “Creating Topics from Domains,” on page 73.

6.1.1 Domain Use CasesThe use of Domains, Domain Topics, and saved reports in JasperServer depends on the complexity of your data and your business needs. Domains and Domain Topics can give users great freedom in designing reports while the security features make sure they do not access inappropriate data. On the other hand, administrators could create very targeted Domains and Domain Topics, then use repository access permissions to make sure users cannot modify them.

In the first case, a Domain could contain dozens of tables in several unjoined sets, perform very little filtering, but define a strong data-level security policy. Users of the Domain might only see a single set of tables according to their security permissions. They could then perform their own filtering, relabel columns for their own needs, and save their settings as a Domain Topic for future reuse in Ad Hoc reports. In this case, there might only be one Domain within the organization but many Domain Topics that users have created for specific needs.

In the other case, Domains can be used to perform complex joins, have formulae for calculating new columns, filter data, and select a small set of columns for specific users or specific types of reports. Perhaps reports also need to be internationalized, so the administrator creates the corresponding locale bundles. In this scenario, there might be many specific Domains, and each would have corresponding locale bundles and a single Domain Topic. Users would have a wide variety of Domain Topics to choose from, each for a specific purpose, but no opportunity to access the Domains to perform their own filtering.

The preceding examples illustrate two extreme cases, but there are many scenarios that combine some degree of both. The number of users in your production environment and their level of proficiency will also determine your general use cases. A small number of users who understand their database might be given administrator privileges to define complex Domains as an extension of the Ad Hoc report design process. On the other hand, with large numbers of users or less database proficiency, administrators will want to create Domains that help the users meet their business goals.

The table in section 4.5.3, “Creating Topics from Domains,” on page 73 gives individual use cases for Domains, Domain Topics, and reports based on Domains.

6.1.2 TerminologyThis chapter refers to both columns and fields. Conventionally, database tables are composed of columns, and columns are composed of fields in each row. Some Domain operations refer to columns, others to fields, however the two terms refer to the same concept from different perspectives. For example, a calculated field refers to a field in row that is computed from the field values in other columns. But the effect of a calculated field in every row is to create a new caluculated column. Similarly, operations such as joins and filters operate on designated field values in a row, but they are defined by the columns that determine the fields involved.

Within a Domain, columns are called items. Because an item may originate from derived tables or calculated fields, it may not correspond to a single column in the database.

6.1.3 Components of a DomainA Domain is saved as an object in the repository. Like other repository objects, it has a name, optional description and folder location specified at creation time. A Domain references the following components:

116

Creating Domains

A JDBC or JNDI data source whose tables and columns will be presented through the Domain. Data sources are selected from previously defined data sources in the repository.The Domain design that specifies tables and columns in data source, queries for derived tables, joins between tables, calculated fields, and labels to display the columns.Optional locale bundles consisting of localized property files to give labels and descriptions in other languages.Optional security file that defines row and column-level access privileges based on users or roles.

The Domain design is either created through a dialog or uploaded from an external XML file. Locale bundles and security files are uploaded from external files. The following sections describe the various dialogs for selecting, creating or uploading the components of a Domain.

6.1.4 Sample DomainsTwo sample Domains are provided in Organization > Domains in the default installation. You can use them to practice designing and using Domains, as well as see complex reports based on Domains:

Simple Domain – Demonstrates very basic features of DomainsBased on the SugarCRM JNDI sample data source.You can export the Domain’s design file as described in section 7.1, “The Domain Design File,” on page 139.Domain used to create Simple Domain Topic in the Organization > Ad Hoc Components > Topics folder, as described in section 4.5.3, “Creating Topics from Domains,” on page 73. Shows how report creator can see the items in a Domain through a Domain Topic.

SuperMart Domain – Demonstrates advanced features of Domains.Based on the Foodmart sample data source.Complex Domain with many tables and joins.You can export the Domain’s design file as described in section 7.1, “The Domain Design File,” on page 139.You can download and inspect the Domain’s security file and locale bundles, as described in section 7.1, “The Domain Design File,” on page 139.

6.1.5 Overview of Creating a DomainIn practice, you should plan your Domain’s features before you begin the creation process. You should decide on the data source and define it in the JasperServer repository. You should know the elements of your design: tables and columns to choose, joins to perform, filters to define, sets you need, and item properties to expose to users. You also need to determine whether the users of your Domain need localized resources, such as translated labels and local formats. And finally, you need to determine a security policy for the data retrieved through the Domain.

There are several dialogs involved in creating a Domain in JasperServer:1. As an administrator user, select Add Resource > Domain in the repository to open the Add New Domain dialog.2. On the Data and Resources page, select a data source then enter a name and optional description for your Domain.3. Launch the Domain Designer and step through its tabs to ultimately define the sets and items of your Domain.4. Optionally define localization bundles or data-level security on the Resources page of the Add New Domain dialog.5. The new Domain is not created until you click Save in the Add New Domain dialog.

The next section gives a detailed example of using these dialogs to create a Domain.

6.2 Example of Creating a DomainThe following example shows how to create a Domain. For complete information on all of the options and settings available for designing reports, see sections 6.3, “Using the Add New Domain Dialog,” on page 125 and 6.4, “Using the Domain Designer,” on page 127.

To create a sample Domain:1. Log in to JasperServer as an administrator and select View > Repository.

117


2. Locate the folder where you want to place the Domain, for example Organization > Domains.3. Right-click the folder and select Add Resource > Domain from the context menu.

The Add New Domain wizard opens to the Data and Design page.

4. Under the Properties heading, enter a name, repository location, and optional description of the Domain. In this example:Display Name is Example DomainLocation is /Domains (unchanged)Description is Created in User Guide tutorial.

5. Under the Data Source heading, click Browse. In this example, expand and select Analysis Components > Analysis Data Sources > SugarCRM Data Source, the click OK.

6. Click Launch Domain Designer on the Create tab under the Design heading.The Domain Designer opens to the Tables tab showing the data source you selected in the previous step. The list of tables to choose from shows all the database tables found in the data source. You can expand each table to see its individual columns.

Figure 6-1 Data and Design Page of the Add New Domain Dialog

Figure 6-2 Select a Data Source Dialog for a New Domain

118

Creating Domains

7. Double-click the following tables in the left-hand list to add them to the list of selected tables:accounts, accounts_opportunities, cases, opportunities, users

With the data source in this example, the check box to Inspect new tables and automatically generate joins has no effect, so you may leave it checked or not.

8. Click Next to display the Derived Tables tab.

Figure 6-3 Tables Tab of the Domain Designer

Figure 6-4 Derived Tables Tab of the Domain Designer

119


9. A derived table is defined by a query and a selection of the columns in the result. Create a derived table as follows:a. Click New and enter a meaningful name in the Query ID field, in this example: p1cases.b. Type the following query:

select * from cases where cases.priority=1 and cases.deleted=false

c. Click Run to see the columns in the result of the query.d. Select the following columns by Control-clicking in the list of query results:

e. Click Create. The new derived table is shown in the list of tables and contains the columns you selected.10. Click Next to proceed to the Joins tab.

The tables selected on the Tables tab and defined on the Derived Tables tab appear in both lists.

11. In the left-hand list, select the users table and click the Copy Table icon to create the users1 table. Select the same

users table again and click the Change Table ID icon , and rename it to users2.

Now there are two table aliases for the users table to avoid circular joins.12. To specify a join, expand the tables to see column names, select a column in the left table list and a column in the right

table list, then click a join icon. For this example, define the following joins:

account_idassigned_user_idcase_number

date_entereddescriptionid

nameresolutionstatus

Figure 6-5 Joins Tab of the Domain Designer

Left Table and Column Right Table and Column Join Type

accounts: id accounts_opportunities: account_id Inner

accounts_opportunities: opportunity_id opportunities: id Inner

opportunities: assigned_user_id users1: id Inner

120

Creating Domains

Outer joins are needed when columns might have null values. In this example, the left outer join includes accounts without P1 cases, and the right outer join includes P1 cases without assigned users.

13. When you have selected all the necessary joins, click Next to proceed to the Calculated Fields tab. The list of available columns shows all the joined and unjoined tables resulting from the joins you defined. In this example, the cases table was used only to help create the p1cases derived table, but itself was not joined to the other tables.

14. Click Create Field to begin, then enter the following details for a calculated field that creates unambiguous city names:Name: city_and_stateType: StringExpression: concat( accounts.billing_address_city, ', ', accounts.billing_address_state )When entering the expression, you can expand the join tree and double-click column names to insert them.

Click OK to validate the expression and add the calculated field to the list of available columns.

accounts: id P1cases: account_id Left Outer

users2: id P1cases: assigned_user_id Right Outer

Figure 6-6 Calculated Fields Tab of the Domain Designer

Left Table and Column Right Table and Column Join Type

121


15. Click Next to proceed to the Filters tab. The list of available columns is identical to the one on the previous tab, including any calculated fields.

16. Define two filters as follows:a. Expand the join tree and the opportunities table in list of Available Fields.b. Click the arrow next to the opportunity_type column to create a condition for it in the Condition Editor.c. Use Equals as the comparison operator, and select Existing Business from the list of available values.d. Click OK to save this condition in the list below.e. Create another condition by expanding the p1cases table and double-clicking the status column.

This also places it in the Condition Editor. If you select the wrong one, click Cancel to clear the Condition Editor.f. Choose the “Does Not Equal” comparison operator and type closed as the value.

JasperServer did not find any values for this column in the data source, but you can still enter a value in this way.g. Click OK to save this condition as well.

Figure 6-7 Filters Tab of the Domain Designer

122

Creating Domains

17. Click Next to proceed to the Display tab.

The join tree is shown on the left again. To the right of it is a list of sets and items that will appear in this Domain. An item is a column or calculated field, along with its display properties, that is chosen to appear in the Domain. A set is a grouping of items independent of the tables in which the columns originate. The table on the right shows the display properties of the set or item selected in the list. Display properties include labels, descriptions that appear as tooltips, as well as default formats and summary functions.

18. Create a hierarchy of item sets and items from the tables and columns in the left-hand list. Only columns from the joined tables in JoinTree_1 will be added to this example Domain.

You can double-click or drag-and-drop sets and items between the two lists.You can also use the icons above the lists to create new sets and move columns into them.To change the order of sets or items, select them and click the arrow buttons to the right of the list.To rename an item or set, select it and double-click its current label in the properties table, then type the new label.Double clicking the description property or clicking ... in the properties table shows the Edit description dialog:

For this example, create the sets and items in the following table. The simplest way is to double-click JoinTree_1 to select all of its tables and columns, remove the unwanted items, and then rename the sets and remaining items and give them descriptions. The names and descriptions shown here are meant to be realistic but do not represent an actual business case.

Figure 6-8 Display Tab of the Domain Designer

Figure 6-9 Edit Description Dialog of the Domain Designer

123


19. Set the data format and summary properties on the following items:Opportunity, Date: data format of Jan 01, 2009Opportunity, Amount: data format of ($1,234) and summary using averageP1 Case, Date: data format of Jan 01, 2009

When used in reports, these items will have the data formats and summary functions by default.20. The example Domain design is finished. Click Done.

The Add New Domain dialog appears again. The Edit tab under the design heading informs you that the design has been created and that you can launch the Domain Designer again to edit it.

21. Click Save in the Add New Domain dialog.The new Domain is stored in the repository folder named in the Location field and appears in search results.

(Set ID) Set LabelSet Description

Item ID Item Label Item Description

(accounts) AccountCustomer account information

name Customer Name of customer

account_type Type Account type

industry Industry Primary industry

annual_revenue Revenue Size Estimated annual revenue

employees Employee Size Estimated number of employees

city_and_state City, State City and state of headquarters

(users1) Account RepPrimary account representative

first_name First Name Given name

last_name Last Name Surname or family name

(opportunities) OpportunitySales opportunity

date_entered1 Date Date opportunity opened

amount Amount Anticipated amount of the contract

probability Probability Estimated chance of winning the contract

description1 Description Description of the opportunity

lead_source Source Lead source

sales_stage Stage Sales stage

(p1cases) P1 CaseHigh priority support cases

case_number Case Case number

date_entered2 Date Date case opened

name2 Summary Name or summary of the case

description2 Description Detailed description of the case

resolution Resolution Description of the case resolution

status Status Current status of the case

(users2) Case RepSupport case representative or engineer

first_name1 First Name Given name

last_name1 Last Name Surname or family name

124

Creating Domains

6.3 Using the Add New Domain DialogThe dialogs entitled Add New Domain and Edit Domain are identical and are used to define all the components of a Domain. There are two pages:

Data and Design – Specify the domain’s data source, its domain design, and the properties of its repository object.Resources – Optionally specify a security file and one or more locale bundles.

You must specify at least a data source, a design or valid design file, and a display name on the Data and Design page before you may navigate to the Resources page or Save a Domain.

To navigate between pages, click the page name at the top of the dialog or the Next and Back buttons at the bottom.The Cancel button exits the dialog without saving any of your Domain settings. For new Domains, no Domain is created; when modifying an existing Domain, it remains unchanged.The Save button validates your Domain components then saves the Domain. For more information, see section 6.3.3, “Domain Validation,” on page 126.

6.3.1 The Data and Design PageThe Data and Design page of the Add New Domain and Edit Domain dialogs lets you specify the mandatory components of a Domain, as well as set its repository object properties. The mandatory components of a Domain are:

A data source selected from the repositoryA Domain design created interactively with the Domain Designer or uploaded from a file

Data Source heading:You may use only data sources that are in the repository and to which your user has access privileges.Click Browse to open a dialog that lets you choose from among all the data sources in your organization. If your data source supports schemas, such as an Oracle RDBMS, you will select schemas when you launch the Domain Designer.Domains may only have JDBC-based data sources.If you installed the sample data, there are sample data sources in Organization > Data Sources and Organization > Analysis Components > Analysis Data Sources. Both contain JDBC data sources that can be use for a Domain.The text field shows the repository path of the chosen data source.

Properties heading:For new Domains, enter a display name and specify a location in the repository by typing or clicking Browse. The default location is the last folder selected in the repository.The location for Domains in the sample data is the Organization > Domains folder, but you may use any location. JasperServer locates Domains by their repository object type, not by their location.

Figure 6-10 Data and Design Page of the Add New Domain Dialog

125


The description field is optional but recommended. The description is displayed with the Domain in the repository and when users are selecting a Domain to create an Ad Hoc report.

Design heading:On the Edit tab, click Launch Domain Designer to open the interactive Domain Designer dialog.On the Upload tab, click in the text field or Browse to specify a design file to upload. For more information, see section 7.1, “The Domain Design File,” on page 139.After using the Domain Designer or uploading a design file, both tabs indicate that a design has been created. You can then edit your design in the Domain Designer again or upload another file to replace the current design.

6.3.2 The Resources PageThe Resources page of the Add New Domain and Edit Domain dialogs lets you upload security and locale bundle files for your Domain. You can use this page to add, replace, or remove any previously uploaded files for your Domain.

The Resources page is documented in section 7.1, “The Domain Design File,” on page 139.

6.3.3 Domain ValidationThe validation of a Domain ensures that all of its components are consistent among each other. The Add New Domain dialog checks the syntax of files when they are uploaded, but overall consistency must be checked when saving the new or edited Domain.

When you click Save, the Add New Domain or Edit Domain dialog performs the following validation. The first four steps are the same as in section 6.4.10, “Domain Design Validation,” on page 134:1. Verify that the tables and columns of the Domain design exist in the data source.

2. In each defined set, verify that all items originate in the same join tree.3. Verify that all items reference existing columns.4. Verify that derived tables have valid SQL queries.5. If a security file has been uploaded, verify that all items and sets in the security file exist in the Domain design.

If validation fails, the Add New Domain dialog remains open and a message appears to help you correct the error. Make the necessary changes to your settings and save again. If the settings are in the uploaded files, you need to edit the files and upload them again.

Figure 6-11 Resources Page of the Add New Domain Dialog

In special cases where you need to create a design before the data source is available, this step can be omitted by setting a parameter in the JasperServer configuration file. See the JasperServer Administrator Guide.

126

Creating Domains

6.4 Using the Domain DesignerThe Domain Designer is an interactive dialog for specifying all the settings in the design of a Domain. Along the top of the Domain Designer are tabs for various aspects of the design:

Tables – Select all tables whose columns you wish to use in the Domain, either directly or indirectly.Derived Tables – Enter queries whose results appear as derived tables available in the Domain.Joins – Define inner and outer joins between all the tables and derived tables.Calculated Fields – Enter expressions whose results appear as calculated fields.Filters – Specify conditions on field values to limit the data accessed through the Domain.Display – Give display properties to various tables and columns to expose them sets and items in the Domain.

Once you have selected the tables on the first tab, you may jump to any tab, but you cannot save your settings until you make a selection on the Display tab.

To navigate between tabs, click the tab name at the top of the dialog or the Next and Back buttons at the bottom.The Cancel button exits the dialog without saving any of your design settings. For new Domains, no design is saved; when modifying an existing design, it remains unchanged.The Done button validates your design then saves it in the Domain, replacing any current design. For more information, see section 6.4.10, “Domain Design Validation,” on page 134.

6.4.1 Designer Tool BarThe tool bar buttons operate on the Domain design in its current state, regardless of which tab is selected.

Check Design – Validates the domain as described in section 6.4.10, “Domain Design Validation,” on page 134.

Export Design to XML – Exports the Domain design in its current state to an XML file.Use this feature if you wish to edit your Domain design in an external editor, for example to duplicate settings with copy-paste or to enter a complex formula. Exporting the XML from the Domain Designer avoids having to write it from scratch. For more information, see section 7.1, “The Domain Design File,” on page 139.

Export Bundle Stub – Exports a Java properties file for the labels and descriptions of sets and items in your design.Use this button to create a template for your locale bundles after you have defined your sets and items on the Display tab. It gives you the option of automatically generating keys based on the set and item IDs. For more information, see section 7.5, “Locale Bundles,” on page 161.

Cancel – Closes the dialog without saving your Domain design and returns to the Data and Design page.Same as clicking Cancel at the bottom of the dialog.

Done – Saves your current selections as the Domain design and returns to the Data and Design page.Same as clicking Done at the bottom of the dialog.

6.4.2 Tables TabThe Tables tab presents all the tables and columns found in the chosen data source so you can select the ones to appear in the Domain. For data bases that support schemas, such as an Oracle RDBMS, you will be prompted to choose one or more schemas, and the Tables tab will present all tables and columns found in those schemas.

Typically, you select the tables that need to be joined, therefore you must understand the logical design of tables in your data source. Additionally, select all tables you wish to reference in your Domain design, even if their columns will not appear directly in the Domain. For example, select the tables containing columns that you will use in a derived table or calculated field.

To be precise, the Tables tab shows all columns that have a supported type listed on page 143. If your data source has special data types such as CLOB or NVARCHAR2, or if you access synonyms on an Oracle database, you need to configure JasperServer to recognize them. See the configuration chapter in the JasperServer Administrator Guide.

127


Click the tree icons beside the table names to inspect the columns of a table. However, only whole tables may be selected on this tab; column-level selections are made on the Display tab.Double-click or drag a table name in the Choose tables list to move it to the Selected tables list. Alternatively, single-click a table name and use the arrow button between the list.To remove a table you do not want, double-click it or drag it out of the Selected tables list. You can also click the double-arrow button to clear the list of Selected tables.The Inspect new tables and automatically generate joins check box creates joins only if your database has been configured with referential constraints (foreign keys). Otherwise, selecting it has no effect. If applicable, the generated joins will appear on the Join tab.The Data Source field at the top shows the name of the data source for your Domain.Click Manage to change the chosen data source. If you change the data source, all of your settings in the Domain Designer that do not have an are discarded.

The Tables tab does not detect changes to your database tables and columns in real-time. To update a Domain after making changes to your database structure, click Done to close the Domain Designer, then launch it again:

New tables and new columns appear in left-hand list; new columns appear under their table name. Because the Tables tab selects entire tables, you must add all new columns together by moving their table name to the right-hand list.For deleted tables and columns that were selected in the Domain, you are prompted to remove them from the right-hand list. When you accept, the Domain Designer removes those columns or tables from the Tables tab. However, if you had selected the dropped columns for display, you must manually remove them from the Display tab, otherwise the Domain will have a validation error. For information about removing columns that were displayed through the Domain, see section 6.5.1, “Maintaining Referential Integrity,” on page 136.

6.4.3 Manage Data SourceDomains assign aliases to data sources, and the Manage Data Source dialog available on the Tables tab lets you set aliases as well as change the data source. The default alias for a data source is the display name of its repository object.

You can edit the alias by double-clicking the alias name and typing a new alias. Usually this is not necessary because the data source alias is not displayed to Domain users.If your data source supports schemas, such as an Oracle RDBMS, click Select Schemas to choose among all available schemas in the data source. All the tables in the schemas you choose will appear in the left-hand list on the Tables tab.The Replace button lets you select a different data source to be associated with the alias. Use this button to replace the data source with an equivalent one. For example, if your database changes servers, you need to create a new data source objet and use it to replace the previous one in your Domain.To change the data source and alias, click Delete to remove the current one, then click Add to open a dialog to select an available data source from the repository.Click OK to apply your changes, or click Cancel to return to the Tables Tab without changing the data source.

[

Figure 6-12 Manage Data Source Dialog of the Tables Tab

When you change the data source, all previous settings in the Domain Designer that do not conform to the new data source will be lost without prompting.

128

Creating Domains

6.4.4 Derived Tables TabA derived table in a Domain is defined by a custom query and a selection of the columns in the result. Because Domains are based on JDBC data sources, the query is written in SQL. The result of an SQL query is a table whose structure and contents are determined by the clauses in the query. For example, the WHERE clause may contain conditions that determine the rows of the derived table. Once a derived table is defined, the columns selected from the result are available for use in the Domain design.

Click New to begin defining a derived table. Type a name for your table in the Query ID field.Enter a valid SQL (JDBC) query in the Query field. Your query may refer to any table or column available in the data source shown. The syntax for a valid SQL query does not include a closing semi-colon (;).Expand the tree icons of the tables in the left-hand list to view column names you may wish to use, but don’t click them.When your query is complete, click Run to test it and see the list of columns in the result.By default, all columns in the result are selected. Use control-click to change the selection. If you only want a few columns out of many, it is easier to specify the column names in the SELECT clause of the query.Click Create to add the derived table with the current selection of columns to the left-hand list of tables and columns. A distinctive icon identifies it as a derived table.

6.4.5 Joins TabJoins create associations between tables so that their rows may be presented together in the same report. Multiple joins associate columns across many tables to create powerful data visualizations when used in reports. The number of tables and joins in your Domain depends on your business needs, as described in section 6.1.1, “Domain Use Cases,” on page 116.

In order to create a join between two tables, each must have a column with the same meaning. For example, a table with data for support cases has a column for the assigned engineer user ID that can be joined with the table of user data that has a user ID column. JasperServer supports the four most common join types, all based on equality between values in each column:

Join Inner – The result will contain only rows where the values in the chosen columns are equal. In the support case example above, the result of an inner join will contain only support cases that have been assigned to a support engineer.

Join Left Outer – The result will contain all the rows of the left-hand table, paired with a row of the right-hand table when the values in the chosen columns are equal and with blanks otherwise. If the support cases are in the left-hand table of the example, the result of a left outer join will contain all support cases even if they do not have an assigned engineer.

Join Right Outer – The result will contain all the rows of the right-hand table, paired with a row of the left-hand table when the values in the chosen columns are equal, and with blanks otherwise. If the users are in the right-hand table of the example, the result of a right outer join will contain all the users and the support case assigned to each, if any. In this example, a user might also appear several times if different support cases refer to the same support engineer user ID.

Full Outer Join – This join type cannot be created directly, it can only be selected by editing an existing join. The result will contain all rows from both tables, paired when the joined columns are equal, and filled with blanks otherwise.

On the Joins tab, the list of selected and derived tables is duplicated in two lists, one to choose the left table, the other to choose the right table. Expand a table in each list, select a column in each table with the same logical meaning and compatible formats, then click one of the join icons. The new join appears below in the list of joins.

In some cases, you may need to duplicate a table in order to join it several times without creating a circular join, or in order to join it to itself. You can also duplicate a table so it may be joined with different tables for different uses. Click the following icons above the left-hand list to make copies of a table:

Copy Table – Copies the selected table and gives it a name with sequential numbering. The copy appears in both lists.

Change Table ID – Lets you edit the name of the selected table. The new name becomes the ID of the table throughout the Domain, and is updated everywhere it appears in the Domain Designer.

Delete Selected Table – Removes the table from both lists. If the deleted table was the only instance of a table, removing it on the Joins tab also removes it from the list of selected tables on the Tables tab.

129


Below the lists of left and right tables, the All Joins tab summarizes the joins you have defined. If you have many joins in your domain, use the Joins on Selected Table tab to see only those defined on the table currently selected in the left-hand list. When you select a join on either tab, you can change the join type by selecting another type in the drop-down list. This list include the Full Outer join type that cannot be created directly.

Delete Join – Removes the selected join definition from the list of joins and from the Domain design.

The result of the Joins tab is a number of join trees that appear on subsequent tabs. For example, if you join tables A and B, B and C, then join tables D and E, there will be two join trees. Columns of table A and table C may appear in the same report because their tables belong to the same join tree. Tables A and D are said to be unjoined; their columns may not be compared or appear in the same report. Tables that are not joined appear individually along with the join trees.

6.4.6 Calculated Fields TabA calculated field is defined by an expression that computes a value based on the values of other columns. In order for the values to be coherent, all columns that appear in the expression for a calculated field must be from the same join tree.

Click Create Field to being defining a new calculated field.Enter a short name for your calculated field. This name becomes the ID of the field in the Domain; you can later give it a descriptive label and full description.Select a datatype for your calculated field. The expression you write must compute a value of this type. For most expressions this is also the datatype of the columns you wish to use in the expression. Therefore, you need to be familiar with the datatypes of the various columns in your data source.Enter the expression to compute the value of your calculated field. The expression uses the Domain Expression Language fully described in section 7.2, “The DomEL Syntax,” on page 150. To insert a reference to the value of another column, expand the join-tree to find its table and double-click the column name. The column name appears in the expression at the cursor, qualified by its table name. Do not insert column reference from unjoined trees, because the calculated fields editor does not validate expressions as they are written.

Click OK to save your new calculated field. The Domain Designer validates the expression and warns you of any errors at this time. If there are errors, use the indications of the error message to help correct the expression. To clear the calculated field editor without saving, click Cancel.Once validated, a calculated field appears in the table or join tree whose columns are used in the expression. Calculated fields have a distinctive icon for easy recognition in the list of columns.

Figure 6-13 Calculated Fields Editor in the Domain Designer

130

Creating Domains

An expression that does not use any columns will have a constant value. For example, you might create an integer field named Count that has the value 1 and later has a default summary function to count all occurrences. Constant fields are independent of join trees and automatically appear in a set called Constants.Calculated fields may be used to compute other calculated fields. Double-click the calculated field name to insert a reference to it into an expression.To view, edit, or delete the definition of a calculated field, cancel any input in the calculated field editor, then click the name of the field in the left-hand list.

Modify its name, its type, or its expression, then click OK to save the new definition.Click Delete Field to remove the calculated field from your Domain design.If you only wanted to view the definition of the field, click Cancel to remove it from the editor.

6.4.7 Filters TabA filter on one or more columns reduces data that is not needed or not wanted in reports based on the Domain. For example, financial reports for the current fiscal year may need data from the previous fiscal year for comparison, but nothing earlier. It is always good practice to filter out irrelevant data to reduce the size of query results and processing time within JasperServer.

Also, reports based directly on the Domain can define their own filters. Putting often-used filters in the Domain design avoids the need for each user to define them independently and also reduces the chance for errors.

You may define a filter on a column that you do not plan to expose in the Domain. The filter will still be active and only data that satisfies all defined filters will appear to report users. For example, you may filter data to select a single country, in which case it doesn’t make sense for the column to appear in a report. However, you should clearly document such data restrictions in the description of your Domain, so that users understand what data is accessible through the Domain.

Select a column in the left-hand list and click Create Condition to begin defining a filter on that column. Alternatively, you can click the arrow next to the column name or double-click the column name.To define a filter that compares two columns of the same datatype, select the second column with a Control-click, then click Create Condition. This button will only be enabled when two columns of the same type are selected. In the Condition Editor, the choice of comparison operators depends on the datatype of the column. For example, string types offer a choice of string search operators and date types have a choice of time comparison operators. The filter value depends on the datatype and the comparison operator. For example, if you select a date column with the “is between” operator, the condition editor will display two calendar icons for specifying a date range.

Text columns have both substring comparison operators such as “starts with” or “contains” and whole string matching such as “equals” or “is one of.” When you select a whole string matching operator, the dialog displays a list of all existing values for the chosen column retrieved in real-time from your database. If there are more than 50 values to display, use the search controls to the left and click to narrow your list of available values. For multiple value matching, double-click the available values to select them. You may perform multiple searches and select values from each list of results.

Figure 6-14 Condition Editor on the Filters Tab of the Domain Designer

131


After choosing the comparison operator and filter value, click OK to define your filter. To clear the condition editor without saving a filter, click Cancel.The list of Current Conditions shows all the filters you have defined. The note at the bottom of the current conditions reminds you that “data rows much match all conditions.” In other words, the overall filter applied to your data is the logical AND of all conditions you have defined.Click a row of Current Conditions to edit it again in the Condition Editor. Click OK to save your changes. After selecting a row, you may also click the Delete Condition button to remove it from the list.

6.4.8 Display TabThe Display tab lets you specify which columns and calculated fields are exposed through the Domain and how they will appear. Typically, only columns that are useful in reports or for further filtering should be selected, and unneeded columns should be omitted to simplify the report creation interface. On the Display tab, you also define display properties for each chosen column, such as a label and description, to further help report creators.

A column along with its display properties is called an item in the Domain. A set is a grouping of items independent of the tables in which the columns originate, however, all items in a set must correspond to columns in the same join tree. Sets are optional; you may create a list of items outside of any sets.

The Join Tree list at the left of the tab contains all the join trees and unjoined tables, including any calculated fields in their defined locations. The list of Sets and Items to the right shows the sets and items that will appear to report creators. You may include any combination of joined and unjoined items in the list of Sets and Items, but when creating a report, users will only be able to include items that originate in the same join tree.

If you only want to display a few of the columns from the join tree, start by creating sets in the right-hand list. Then add items chosen among the columns of the left-hand join tree.

Add New Set – Creates a new set or subset in the list of sets and items. If no set is selected it creates a top-level set; if a set or item within a set is selected, it creates a subset.

Change Label – Lets you edit the name of the selected set or item. The label name is also updated in the list of properties.

Add Selected – Make a selection in the join tree and click this icon: tables are added as sets, and columns are added as items outside of any set. You can also drag-and-drop tables and columns from the join tree to the list of sets and items.

Add to Set – Select a destination set in the right-hand list, then make a selection in the join tree and click this icon: tables are added as subsets, and columns are added as items within the destination set. You can also expand sets in the right-hand list and drag-and-drop tables and columns to the destination set.

If you want to display all or most of your tables and columns in the join tree, double-click the join tree name or drag-and-drop it to the list of sets and items. All tables are created as sets, and the columns they contain are created as items within the sets. Then remove any unwanted sets or items individually from the right-hand list as follows:

Delete (above Sets and Items) – Removes the selected set or item from the left-hand list. You can also double-click the object or drag-and-drop it to a blank area of the join tree list. Removed items automatically reappear in the join tree or table where they originated in the left-hand list.

The left-hand list also offers an alternative view mode: click Table List just below the icons. The table list displays the list of unjoined tables and derived tables, as they appear on the Join tab. It also activates the following icons:

Add All (active only if the right-hand list is empty) – Creates all the tables as sets and all the columns they contain as items in the right-hand list. You can then remove any unwanted sets or items from the right-hand list as described above.

Change Table ID – Lets you edit the name of the selected table. The new name becomes the ID of the table throughout the Domain, and is updated everywhere it appears in the Domain Designer.

Delete Selected (above Table List) – Removes the currently selected table from the left-hand list and from the Domain altogether. The table is removed from the Joins tab, and any joins with this table are deleted. Use carefully.

132

Creating Domains

After your list of sets, subsets, and items is defined, refine your Domain display by reordering them, renaming them, and providing descriptions for them:

To change the order of sets or items, select the objects and use the arrow buttons to the right of the list to move them up or down. You can reorder items within a set and sets within the list, but items and subsets may not be moved into other sets. To achieve this, remove the item or subset and add it again in the new set. Subsets always appear after the items in a set.To rename a set or item, select it then click the Change Label icon or double-click its label in the properties table.To add a description to a set or item, select it then double-click its description in the properties table. Set and item descriptions appear as tooltips in the Ad Hoc Editor and help report creators understand their purpose.

6.4.9 The Properties TableThe properties table is located on the Display tab to the right of the list of sets and items. It lets you view and edit the display properties for the currently selected set or item. The display properties determine how the sets and items will appear to users of the Domain. When the left-hand list displays the Table List, the properties of tables and columns can also be viewed.

The following properties are available, depending on the selected object:Table – The name of the table and the name of the data source (view-only)Field (column) – The name of its table in the data source and its Java datatype (view-only)Set – The label, description, and internationalization keys (view and edit)Item – The label, description, internationalization keys, and default format and summary properties (view and edit)

Table and field properties appear only when Table List view is enabled. All table and field properties are read-only. For sets and items, properties shown in red are read-only. All others you can double-click to edit, or click ... to edit the description.

The label and description help report creators understand the data represented by the set or item. The internationalization keys are the property names of internationalized strings in locale bundles. The data format and summary properties determine how the item will appear by default in a report. The following table describes each of the properties in detail.

Figure 6-15 Table of Properties on the Display Tab of the Domain Designer

Property Appears On Description

ID Table, FieldSet, Item

An identifier used within the Domain. Table and field IDs are based on the names in the data source, but you may change the ID of a table as long as it remains unique. Set and item IDs are a separate namespace in which each ID must be unique, although based on table and field IDs by default.When creating a Domain, you may change any set or item ID as long as it is unique among all set and item IDs. When editing a Domain that has been used to create Topics and reports, you should not change any IDs. For more information, see 6.5.1, “Maintaining Referential Integrity,” on page 136.

Data Source Table, Field Alias of the data source for the selected field or table.

Source Table Table, Field Name of the selected table or of the field’s table in the data source. Does not change when the ID property of a table is modified.

Type Field Java type of the selected field.

133


Labels and descriptions may contain any characters, but the ID property value must be alphanumeric and not start with a digit.

If you wish to edit the properties for a large number of sets and items, the following buttons in the tool bar can help:

Export Design to XML – Lets you edit the properties of your sets and items within an XML file. For a large number of sets and items, this could be faster than using the properties table on the Display tab.

For more information about saving and uploading XML, see section 7.1, “The Domain Design File,” on page 139.

Export Bundle Stub – Generates the internationalization keys if needed and saves them to a file that serves as a template for your locale bundles. Make sure your set and item IDs are finalized because they are used to generate the keys. The generated keys are added to your Domain design and appear in the table of properties.

For more information about the internationalization keys, see section 7.5, “Locale Bundles,” on page 161.

6.4.10 Domain Design ValidationThe Domain Designer must ensure that all tables and columns are consistent with the data source. Validation is important because the Domain design may include derived table queries and calculated field expressions entered by the user.

Validation occurs at the following times:When opening the Domain Designer. This will detect any inconsistencies in Domain designs from uploaded files.In certain cases, when navigating from tab to tab. This will detect problems on the tab where they occur.If you change the data source.When you export the design file.When you click the Validate tool bar icon. See section 6.4.1, “Designer Tool Bar,” on page 127.When you click Done to exit the Domain Designer.

Validation performs the following steps:1. Verify that all tables and columns exist in the data source.

2. In each defined set, verify that all items originate in the same join tree.

Label Set, Item User-friendly name displayed in the Choose Ad Hoc Data wizard and the Ad Hoc Editor.

Description Set, Item User-friendly description displayed as tooltip on the label in the Ad Hoc Editor. The description helps the report creator understand the data represented by this set or item.

Label ID Set, Item Internationalization key for the label property; locale bundles associate this key with the localized text for the set or item label.

Descr. ID Set, Item Internationalization key for the description property; locale bundles associate this key with the localized text for the set or item description.

Source Item References the Domain names of the table and field associated with this item; the syntax is Domain_jointree.Domain_table.datasource_field.

Data Format Item Default data format for the item when used in a report. The data format is a numerical or date format, for example ($1,234) or 01/01/2009. Items with string values do not have a data format.

Summary Item Default summary function for the item when used in a report. Numerical items have functions such as sum or average, all others let you count distinct values or count all values.

In special cases where the design is created before the data source is complete, this step can be omitted by setting a parameter in the JasperServer configuration file. See the JasperServer Administrator Guide.

Property Appears On Description

134

Creating Domains

3. Verify that all items reference existing columns.4. Verify that derived tables have valid SQL queries.

Unless you clicked the Validate tool bar icon, there is no message when validation succeeds. However, a message appears when validation fails to help you correct the error.

6.5 Editing a DomainYou can edit a Domain by changing, adding to, and deleting its components.

To edit a Domain:1. Log in to JasperServer as an administrator and select View > Repository.2. Browse or search the repository to locate the Domain, typically by setting the Domain filter.3. Right-click an existing Domain and select Edit from the context-menu.

The Domain appears in the Edit Domain dialog. This dialog is identical to the Add New Domain dialog documented in section 6.3, “Using the Add New Domain Dialog,” on page 125.

4. Under the Properties heading, you can change the display name or description of the Domain’s repository object.To change the location of a Domain, use the repository manager to move the Domain object to a different folder.

5. Under the Data Source heading, click the path or click Browse to change the data source for your Domain.

6. Under the Design heading, select the Edit tab and click Launch Domain Designer. For instructions, see section 6.4, “Using the Domain Designer,” on page 127. Alternatively, select the Upload tab, and click Browse to locate a Domain design file. This allows you to reimport the XML file of your Domain design after exporting it and making modifications in an external editor. See also “Maintaining Referential Integrity” below if you need to remove items in your Domain.

7. If you wish to add or replace the security file or locale bundles for the Domain, click Next or Resources. The Resources page is further documented in section 7.1, “The Domain Design File,” on page 139.

Use extreme caution when editing Domains that might have been used for reports and Domain Topics. A Domain specifies the data source for the Domain Topics and reports that are based on the Domain. They might fail if the underlying Domain is edited; they will certainly fail if the underlying Domain is deleted.Before you proceed, see section 6.5.1, “Maintaining Referential Integrity,” on page 136.

Figure 6-16 Data and Design Page of the Edit Domain Dialog

Changing the data source only makes sense in certain cases, for example if your data source definition changes slightly but not the underlying database. If you change to a data source with a different database, the definitions in your Domain design will no longer be valid and you will not be able to save the Domain.

135


8. When done, click Save to update the Domain with your changes. To close the dialog without modifying the Domain stored in the repository, click Cancel.

9. After modifying a Domain, you must clear your Ad Hoc cache of all queries based on the Domain. This will remove any data that was based on the old instance of your Domain and avoid inconsistencies in new reports. For instructions, see the JasperServer Administrator Guide.

6.5.1 Maintaining Referential IntegrityWhen editing an existing Domain, it is up to the user to maintain the referential integrity between the items in the Domain and any Domain Topics or reports that have been created from the Domain. Referential integrity means that at the time a Domain Topic or report is opened or run, all the items that it references are still defined in the Domain. If you modify a Domain by removing sets or items, you must be sure that no Domain Topics or reports are based on that item. Even if the underlying tables and columns still exist in the database, the sets and items referenced in the Domain must still exist in the Domain.

Any report that references a deleted item will no longer run, nor can it be opened in the Ad Hoc Editor again. A Domain Topic that references a deleted item will cause errors when used in the Ad Hoc Editor. You can, however, open a Domain Topic for editing and remove references to deleted items. However, that only allows new reports to use the Domain Topic, it does not fix the broken reports based on the items deleted from the Domain Topic.

The granularity of referential integrity is at the individual set and item level. This means that changes to sets and items that are not used in a given report or Topic do not affect the report or Topic. For example, if you delete an item used by Topic A but not Topic B, then Topic A will fail and reports based on Topic A that included the item will fail. But Topic B and its reports are unaffected, as are any reports based on Topic A that did not include the deleted item.

6.5.2 Fixing Referential IntegrityNormally, the solution for maintaining referential integrity is to avoid deleting items from a Domain if they might be in use. Sometimes, it becomes necessary to remove an item or set from a Domain. This may occur if it was erroneously included in the first place and found to expose data that should not be exposed. It may also occur if the underlying database changes so that the item is no longer valid.

In a typical scenario, an administrator or data analyst creates a Domain and many end-users create Topics and reports based on it. When deleting Domain items in a case like this, it is necessary to communicate with users beforehand, so that each may modify his or her reports that use the item. However, there is inevitably a report that is not updated, and the user will require support to fix the broken report. Instead, JasperServer provides a mechanism to replace the deleted item with a placeholder, allowing the user to open the report and edit it, even after the original item has been removed.

The following procedure explains how to fix referential integrity with placeholder items.1. The Domain in this example is similar to the one in section 6.2, “Example of Creating a Domain,” on page 117.

However, the creator accidentally exposed the accounts_opportunities table that contains no useful columns and is necessary only to join the accounts and opportunities tables. Unfortunately, some users were confused by the additional items and used the date_modified item in their reports.

Domain items are identified by their IDs and the IDs of the sets in which they are located. Changing the ID of an item or moving it to a different set will also make it unavailable to any Topics and reports that referenced the ID. To change the name of an item or set, edit its label property, not its ID (see section 6.4.9, “The Properties Table,” on page 133). Moving an item must be treated as deleting it from its current location so it can be added elsewhere.

136

Creating Domains

Figure 6-17 below shows the Domain open in the Display tab of the Domain Designer. We remove the accounts_opportunities set and all its items by selecting it and clicking the Delete icon ,

2. Figure 6-17 also shows the warning dialog about referential integrity. The dialog shows all the items that are deleted and the information necessary to replace them with placeholders. For each deleted item, the dialog lists the item label, the set and items IDs as a path, and the data type of the item.From the dialog, we learn that the date_modified item that we need to replace had the ID date_modified1 in a set with the ID accounts_opportunities, and was of the type java.sql.Timestamp.

3. Click the Calculated Fields tab of the Domain Designer. A calculated field is essentially a custom column of a user-selected type, and that is what we need to create a placeholder. Since the value of the column is not important, we create a constant value that will be recognized as a placeholder should it actually appear in a report.Click Create Field and enter values as shown in Figure 6-18. We use the ZZ prefix on the name to distinguish it from other meaningful columns in the Domain. The most important setting is the type, which must match the type of the item that this placeholder will replace, in this case a timestamp. Then we enter an expression that gives a constant value of the same type. For the syntax of calculated field types, see section 7.2.1, “Datatypes,” on page 151.

4. Now click the Display tab of the Domain Designer. Placeholder items must be located in placeholder sets that mimic the same structure as the original item that was deleted. In this example, the set was deleted along with the item, so we must create a placeholder set as well. In general, the placeholder item must exist in exactly the same path of nested sets as the original item.

Figure 6-17 Deleting Items From an Existing Domain

Figure 6-18 Creating a Calculated Field of the Same Type

137


Click the Add New Set icon to create the placeholder set. Now expand the list of Constants to select ZZdate_modified created above. Click the Add to Set icon to create the placeholder item from the calculated field,

as shown in Figure 6-19.

5. Now we edit the properties of the placeholder set and item so that they will effectively replace the deleted item. Select the placeholder set created above and double-click its ID property, then enter the ID value of accounts_opportunities that we noted in step 2. Now select the new item created above and double-click its ID property, then enter the ID value of date_modified1, also noted in step 2.Figure 6-20 shows the properties for the placeholder item and set after they have been modified. We set the label and description to distinguish the placeholders from real items and discourage their use when seen by users in the Ad Hoc Editor. The IDs are not visible to users, but now that they are identical to those of the deleted item and set, the placeholder will be substituted in reports and in the Ad Hoc Editor, ensuring that the report can be opened and run.

6. Click Done in the Domain Designer and then Save in the Edit Domain dialog.

Alternatively, you can edit the XML design file of a Domain to fix referential integrity. Conceptually, the modifications are the same as described in this procedure, but the order is slightly different:1. Instead of deleting the item, first create the constant calculated field. You can even do this in the Domain Designer before

exporting the design file. You must be familiar with the design file syntax to create the calculated field with the correct type and expression, as described in section 7.1.3, “Structure of the Design File,” on page 141.

2. Then locate the item definition and change its resourceID so that it references the newly created calculated field. This will remove the reference to the unwanted column, and replace it with an item that references the placeholder field.

3. Update the other properties of the item and its enclosing set, using the values shown in Figure 6-20 above. For more information, see section 7.1.3.6, “Representing Sets and Items in XML,” on page 147.

4. Save the design file and upload it, as described in section 7.1.4, “Uploading a Design File to a Domain,” on page 150.

Figure 6-19 Inserting the Calculated Field as a Placeholder

Figure 6-20 Setting the ID Properties to Match the Deleted Item

138

Advanced Domain Features

7 ADVANCED DOMAIN FEATURES

Both the security file and locale bundle are optional components of a Domain. When implemented, they provide data access permissions and localized strings for reports based on a Domain. Data security and localized strings are defined in external files that Domain creators must upload to the Domain. Both take effect in the Ad Hoc Editor when creating the report and in the final output when running the report.

In addition, the Domain design itself can be exported to an XML file and edited outside of JasperServer. This gives Domain creators an alternative way to specify the design and allows Domains to be shared between systems. This chapter documents the syntax for each of these files and the considerations necessary when writing or modifying their contents. We start with the Domain design file because the security file and locale bundles rely on certain values it contains.

For a definition of the terms column, field, and item as used in Domains, see section 6.1.2, “Terminology,” on page 116.

This chapter contains the following sections:The Domain Design FileThe DomEL SyntaxResources of a DomainThe Domain Security FileLocale Bundles

7.1 The Domain Design FileThe design of a Domain specifies the selection of tables in the data source, any derived tables, joins, calculated fields, and filters, as well as how those elements will appear to users. In JasperServer, the Domain design can be created interactively through the Domain Designer dialog, however there is also an XML file format for exporting and uploading the settings. The text file containing a Domain design represented in XML is called a design file.

The XML in a design file is a hierarchy of elements and attributes on those elements that specifies all the settings in the Domain. The elements and attributes are defined by an XML schema provided in an XSD file. In addition, there are constraints on a Domain design that are not expressed in the XML schema. A design file can be modified or written from scratch in an editor and uploaded to JasperServer, as long as it conforms to the XML schema and the design constraints.

There are several common use cases for working with design files:

XML is not the native format of the Domain design. The XML file is only a representation from which the design can be inferred. A design has additional constraints that are not mapped in the XML format.

139


Completing the elements of a new design. Use the Domain Designer to define as much of the design as possible, then export the design file and add your handwritten code to the exported file. For example, you can enter the SQL query for a derived table or complex expressions for a calculated field. Working with very large Domains. The Domain Designer makes it easy to select all tables and columns and expose them as sets and items, but editing the labels and descriptions of dozens of items is faster when they appear in a single design file.Repetitive changes to an existing Domain design. If your database changes or you want to move a design file to a different system, you may need to edit each table or item in the design in the same way. Using search-and-replace on an external editor will do this quickly.Creating locale bundles and security files as described in the other sections of this chapter. These other resource files refer to elements of the Domain design, and it is often more convenient to copy-paste them between external files.Creating a Domain design from scratch. It is possible to write a valid XML file that meets the constraints of JasperServer and defines a Domain design. However, due to the complexity of creating a valid design file, it is much easier to begin with a basic design file exported from the Domain Designer or to modify an existing design file.

After editing, a design file can be uploaded, validated, and used to define the design of a new or existing Domain. When you open the design in the Domain Designer again, your modifications will appear and be editable in the Designer. For example, a description you added in the XML design file will appear in the Properties table of the Display Tab, and you will be able to edit it again the Designer. Other elements of the XML file will appear on some or all of the Designer tabs.

7.1.1 Exporting the Design File from a DomainThe design file of a Domain can be exported from the Domain Designer dialog and saved as an XML file. The file will contain the current state of the Domain in the Domain Designer.

To export a Domain’s design file:1. Log in to JasperServer as an administrator and select View > Repository.2. Browse or search the repository to locate the Domain, typically by setting the Domain filter.3. Right-click an existing Domain and select Edit from the context-menu.

The Domain appears in the Data and Design page of the Edit Domain dialog.4. On the Edit tab under the Design heading, click Launch Domain Designer.

The Domain Designer opens to the Tables tab. The tabs of the designer show you the design settings for this Domain that will be exported to XML.

5. In the tool bar at the upper-right of the dialog, click the Export Design to XML icon .

JasperServer validates the design before exporting the XML file. If errors are found, you can cancel the export. For more information, see section 6.4.10, “Domain Design Validation,” on page 134.

6. Your browser will download the XML file and usually give you the choice of viewing or saving the file. To save the design file, select a location and give it a name. Be sure to keep the .xml suffix.

7.1.2 Working With a Design FileThe relationship between item definitions, column definitions, and actual database columns is the essence of the Domain itself and must be maintained when editing the design file. In order to be usable when uploaded to a Domain, a design file must meet the following conditions:

It must be well-formed XML. This means that all syntax, spelling and punctuation is correct so that the file contains a hierarchy of elements, attributes and content.It must be valid with regards to the XML schema. The XML schema defines element and attribute names that are allowed and how they are nested to create a hierarchical structure. This ensures that the elements and attributes are the same ones with the same meaning used by JasperServer. The XML schema of a Domain design is given in the XSD file is located in:

<install-dir>/samples/domain-xsd/schema_1_0.xsdThe design file must be internally consistent and define all the necessary elements of a Domain design. These are constraints that cannot be expressed in the XSD file because they are outside the scope of an XML schema.

140


The tables and columns in the design must be consistent with their external definition in the data source of the Domain. The design must references valid table and column names in the data source; in particular, table names for a design based on an Oracle RDBMS must include the schema name. The data source also defines the datatype of a column, and the design must use that column accordingly. As a result, a design file is specific to a given data source and will most likely fail when used in a Domain with a different data source.

In addition, the more complex elements of a design file have further constraints:SQL queries for a derived table must be valid with respect to the JDBC driver for the data source. Also, the tables and columns in the query must exist in the data source, and the columns in the results must match those declared in the design.Expressions for filters and calculated fields must be valid programmatic expressions in a local format called Domain Expression Language (DomEL). This format is documented in section 7.2, “The DomEL Syntax,” on page 150.

As with any XML file, a design file is plain text and can be edited in any text editor. JasperServer exports well-formatted XML, and if you only want to make a few changes or simple additions, a text editor is sufficient. For editing the content of the design file, a specialized XML editor will ensure that the design file is well-formed, so you don’t introduce other errors. If you want to make structural changes or write a design file from scratch, use an XML editor that understands the XML schema in the schema_1_0.xsd file. By loading both the XML and XSD files, this type of XML editor lets you insert elements and attributes only in the places they are allowed to ensure that the design file is valid.

However, no editor can enforce the internal and external constraints on a design file. The following section explains all of the possible elements and attributes of an XML design file and the various constraints you must maintain on each of them.

7.1.3 Structure of the Design FileThis section explains each of the XML elements and attributes in a design file and how they relate to the settings in the Domain Designer. The sample XML code is taken from the example Domain created in 6.2, “Example of Creating a Domain,” on page 117, although some elements have been added to show structures that did not appear in the example.

The top-level container elements of a design file are schema, itemGroups, items, and resources:

schema – The outer-most container element of a design file (originally called the schema file of a Domain). When exported from the Domain Designer, the schema element includes the xmlns and version attributes.

The xmlns attribute specifies an XML namespace for all element names. This string must be unique to Jaspersoft, but it does not correspond to a valid URL. For more information, see http://www.w3.org/TR/REC-xml-names.The version attribute gives the version of the XSD used to create this design file.

The design of a Domain is stored internally in the repository. The XML is only a representation from which the design can be inferred, and it may have some validity errors that cannot be detected. As a result, the Domain resource and the XML may not remain totally synchronized through several cycles of exporting to XML, editing, and uploading. For example, the Domain Designer sometimes renames the result of a join (JoinTree_1), which affects the security file.However, the Domain Designer also has limitations and cannot create some valid designs. For example, in a design file, you may select the columns of a table whereas you can only select whole tables on the Tables tab. Furthermore, the Domain Designer cannot read some valid designs, in which case you must not open the uploaded design file in the Domain Designer. These rare cases are documented in the following sections.

Because certain XML elements correspond to objects in the Domain design, this section refers to XML elements that contain Domain objects such as sets. This is a short-hand description that means the XML elements contain other XML elements that represent the Domain objects.

<schema xmlns="http://www.jaspersoft.com/2007/SL/XMLSchema" version="1.0"schemaLocation="schema_1_0.xsd">

<itemGroups>...</itemGroups><items>...</items>

<resources>...</resources>

</schema>

141

http://www.w3.org/TR/REC-xml-names/


The schemaLocation attribute is often added by XML editors to locate the XSD file.itemGroups – Contains all the sets and items within sets in the Domain. Along with items, this element corresponds to all the sets and items defined on the Display tab of the Domain Designer. Therefore, itemGroups and items define what users will see when they create a report based on this Domain. The sets and items defined under itemGroups and items must be internally consistent with the tables and columns under resources.items – Contains all the items that are not within sets. These correspond to the items at the root level of the Display tab. When all items are contained in sets, this element is absent.resources – Contains all the definitions of columns, tables, derived tables, joins, calculated fields, and filters in the design, analogous to their definitions on the corresponding tabs of the Domain Designer. Because the elements under resources refer to data base objects, they must be externally consistent with the data source intended for this Domain.

Even though the itemGroups appear first in the design file, this section will document the resources first so that design elements are presented in the same order as the tabs of the Domain Designer.

The resources element contains the jdbcTable and jdbcQuery elements to represent database tables and derived tables, respectively. Join trees are represented as a jdbcTable element with additional contents to define the joins.

7.1.3.1 Representing Tables in XML

In the Domain Designer, you can only select entire tables, not individual columns. In the XML design file, however, you can specify any subset of columns that you need.

<resources><jdbcTable datasourceId="SugarCRMDataSource" tableName="accounts" id="accounts">

...</jdbcTable><jdbcTable datasourceId="SugarCRMDataSource" tableName="accounts_opportunities"

id="accounts_opportunities">...

</jdbcTable><jdbcTable datasourceId="SugarCRMDataSource" tableName="opportunities"

id="opportunities">...

<filterString>opportunity_type == 'Existing Business'</filterString></jdbcTable><jdbcQuery datasourceId="SugarCRMDataSource" id="p1cases">

<fieldList><field id="account_id" type="java.lang.String"/><field id="assigned_user_id" type="java.lang.String"/><field id="case_number" type="java.lang.Integer"/><field id="date_entered" type="java.sql.Timestamp"/><field id="description" type="java.lang.String"/><field id="id" type="java.lang.String"/><field id="name" type="java.lang.String"/><field id="resolution" type="java.lang.String"/><field id="status" type="java.lang.String"/>

</fieldList><filterString>status != 'closed'</filterString><query>select * from cases where cases.priority=1 and cases.deleted=false</query>

</jdbcQuery><jdbcTable datasourceId="SugarCRMDataSource" tableName="users" id="users1">

...</jdbcTable><jdbcTable datasourceId="SugarCRMDataSource" tableName="users" id="users2">

...</jdbcTable><jdbcTable datasourceId="SugarCRMDataSource" tableName="accounts" id="JoinTree_1">

...</jdbcTable>

</resources>

142


jdbcTable – Represents a table or a copy of a table in the data source. A Domain design must reference all the tables that it needs to access. The jdbcTable element is also used to describe join trees, but this case is documented separately on page 144. All three attributes of jdbcTable are required:

datasourceId – Alias that identifies the data source. When created in the Domain Designer, this is the data source alias defined in section 6.4.3, “Manage Data Source,” on page 128. When creating a design file, this alias may be any name you choose, but it must be identical for all tables and derived tables. When uploading the file, the datasourceId will automatically become the alias associated with the data source defined for your Domain. tableName – Literal name of the table in the data source. For a Oracle RDBMS, the table name includes the schema name in the form schema_name.table_name.id – Table ID that is used to reference the table in the Domain design. If you copy a table in order to join it multiple times, each has the same datasourceId and tableName but must be given a different id.

fieldList – A container for field elements. Required on jdbcTable elements because it would not make sense to have a table without columns in the Domain design. You must reference all the columns that you use in the Domain.field – Represents a column of a table in the data source. All the columns that you want to reference in the Domain defined with this element. Both attributes of field are required:

id – Literal name of the column in the data source. As in the JDBC model that the data source is based on, the id must be unique within the jdbcTable, but not necessarily within the Domain.type – The Java type of the column, as determined from the data source by the JDBC driver. The type is one of the following:

Unless you know the name and type of every column in the data source, it is often easier to select and export tables from the Domain Designer. The Domain Designer accesses the data source to find the names of all tables and columns, as well as their types. You may then export the XML design file with this information and refine your design.

7.1.3.2 Representing Derived Tables in XML

Derived tables are similar in structure to tables, but they use the jdbcQuery element which contains the query element:jdbcQuery – Represents a derived table that is the result of an SQL query. Both attributes of jdbcQuery are required:

datasourceId – Alias that identifies the data source for the Domain. The alias designates the data source that will be queried. In the design file, this alias must be identical for all tables and derived tables.id – Table ID that is used to reference the derived table in the Domain design. Any reference to the id of a jdbcTable may also reference the id of a derived table.

fieldList – A required container for the field elements. When the derived table is created in the Domain Designer, the set of columns corresponds to the selection of columns in the query result on the Derived Tables tab.field – Represents a column in the results of the query. Only the columns represented by a field element are available for reference by other elements. The columns of a derived table must be among those returned by the query.

id – Literal name of the column in the query result. If your query gives an alias to the column in a SELECT AS statement, the id is the same as the alias. The id must be unique within the query results, but not necessarily within the Domain.type – The Java type of the column, as determined from the data source by the JDBC driver.

query – The SQL query sent to the database server. Any valid SQL can be used, as long as the columns in the result match the id and type of all field elements of the derived table given in the fieldList. If you add a derived table in the Domain Designer, it will run the query and generate columns based on the result set. You could then export the design file containing the generated column list. The syntax for a valid SQL query does not include a closing semi-colon (;).

java.lang.Booleanjava.lang.Bytejava.lang.Characterjava.lang.Double

java.lang.Floatjava.lang.Integerjava.lang.Longjava.lang.Short

java.lang.Stringjava.math.BigDecimaljava.sql.Datejava.sql.Time

java.sql.Timestampjava.util.Date

If you have proprietary types in your database, JasperServer may not be able to map its Java type from the JDBC driver. You can configure the mapping for proprietary types, as described in the JasperServer Administrator Guide.Alternatively, you can override any mapping by specifying the type attribute for any given field in the XML design file. JasperServer will use this Java type for the field, regardless of its mapping. If your proprietary type cannot be cast in the specified type, JasperServer will raise an exception.

143


The following sample query selects some columns, including a field calculated in the SQL, from the result of a join with sorted results. In this case, only exp_date, store_id, amount, currency, conv, and as_dollars can be exposed as columns of this derived table.

A derived table provides an alternative way to create joins and calculated fields. Here are some things to keep in mind when deciding how to implement your Domain:

Unlike joins defined in the Domain, joins within a derived table are not restricted to equality comparisons when uploaded to the Domain Designer. For more information, see section 7.1.3.3, “Representing Joins in XML,” on page 144.Unlike calculated fields in DomEL, calculated fields within derived tables may use any function call recognized by the RDBMS. See section 7.2, “The DomEL Syntax,” on page 150 for restrictions on function calls in calculated fields.The Domain mechanism applies filters, aggregation, and joins to derived tables by wrapping the SQL in a nested query, which may be less efficient on some databases than the equivalent query generated for a non-derived table

7.1.3.3 Representing Joins in XML

A join is represented in the design file as a special jdbcTable element. It contains the joinInfo and joinedDataSetList elements to define the actual joins. It also contains a list of columns that are exposed through the Domain, each with a prefix on the field id attribute to identify its originating table. The Domain Designer automatically exposes all columns of all tables in a join, but in the design file you only need to specify those you wish to reference elsewhere in the Domain.

jdbcTable – Represents the results of one or more joins between tables. If not all tables are joined together, there is one jdbcTable representing each join tree and containing only the join expressions for that tree. To define the join, the attributes and elements have a different meaning than for a regular table.

datasourceId – Alias that identifies the data source for the Domain. The alias designates the data source where the join will be performed. In the design file, this alias must be identical to that for all tables and derived tables.

<query>select e.exp_date, e.store_id, e.amount, c.currency, c.conversion_ratio conv,

amount * c.conversion_ratio as_dollars from expense_fact e join currency c

on (e.currency_id = c.currency_id and date(e.exp_date) = c.date)order by e.exp_date

</query>

<jdbcTable datasourceId="SugarCRMDataSource" id="JoinTree_1" tableName="accounts"><fieldList>

<field id="accounts_opportunities.account_id" type="java.lang.String"/>...

</fieldList><joinInfo alias="accounts" referenceId="accounts"/><joinedDataSetList>

<joinedDataSetRef><joinString>join accounts_opportunities accounts_opportunities on

(accounts.id == accounts_opportunities.account_id)</joinString></joinedDataSetRef><joinedDataSetRef><joinString>join opportunities opportunities on

(accounts_opportunities.opportunity_id == opportunities.id)</joinString></joinedDataSetRef><joinedDataSetRef><joinString>join users1 users1 on

(opportunities.assigned_user_id == users1.id)</joinString></joinedDataSetRef><joinedDataSetRef><joinString>left outer join p1cases p1cases on

(accounts.id == p1cases.account_id)</joinString></joinedDataSetRef><joinedDataSetRef><joinString>right outer join users2 users2 on

(users2.id == p1cases.assigned_user_id)</joinString></joinedDataSetRef>

</joinedDataSetList></jdbcTable>

144


id – ID that is used to reference the join results in the Domain design. In the Domain Designer, each join tree is automatically given the ID JoinTree_n, where n is a sequential number. In the design file, you can give the join any name you wish, as long as it is unique among all other tables and derived tables.tableName – Literal name of the first table in the join. This table name is combined with those in the joinInfo and joinedDataSetList to define the join expressions. For an Oracle RDBMS, the table name includes the schema name in the form schema_name.table_name.

fieldList – A required container for the field elements in the join tree.field – Represents a column in the join tree. The table of each column is identified by a prefix on the id attribute. When created in the Domain Designer, the design file includes every column in every table of the join. When you create your own design file, only the columns you wish to reference are needed. Both attributes of field are required:

id – Field ID composed of the ID of the table in the design and the literal name of the column in the data source. The syntax is table_ID.field_name.type – The Java type of the column, identical to the type in its table definition.

joinInfo – Gives the table ID and alias for the table given by the tablename attribute. The table ID and alias are used as the first table in the join definition. This element and its two attributes are required even if they are identical.

alias – Alternative name within the join expression for the table identified in referenceId. By default, the alias is the same as the referenceID, but you may supply a true alias in handwritten design files. If you use a distinct alias, you must be careful to use the alias throughout the joinString element that defines the join.referenceId – Table id of the table within the design whose data source name is given in tableName.

joinedDataSetList – Container for the list of join statements.joinedDataSetRef – Container for the join statement.joinString – A string expressing an SQL join statement in the following format:

join_type join table_ID table_alias on join_expressionWhere:

join_type – One of right outer, left outer, or full outer. Inner join is the default if no join type is specified.table_ID – The ID of a table within the design.table_alias – Alternative name to use for the table_ID within the join expression. By default, the alias is the same as the table_ID, but you may supply a true alias in handwritten design files.join_expression – Expression that compares the columns on which the join is made, in the form

left_table_alias.field_name == right_table_alias.field_name

The order of joinedDataSetRef elements is important. The first one must contain a join expression between the table_alias it defines and the alias in the joinInfo element. The subsequent ones may only reference the table_alias they define and ones that appear in joinString elements before them.

7.1.3.4 Representing Calculated Fields in XML

Calculated fields are defined as regular columns in a field element with an additional attribute. Calculated fields that rely only on columns of the same table appear in jdbcTable for that table, as well as in the join tree. Calculated fields that rely on columns from different tables that are joined appear only in the join tree.

The following example shows the XML for a calculated expression in the accounts table. Because it references only the columns of accounts, it appears in that table and in the join tree.

Join expressions are actually written in the DomEL syntax to allow more complex expressions, such as boolean operators and other comparisons. See section 7.2, “The DomEL Syntax,” on page 150.However, join expressions other than equality between field values are not supported in the Domain Designer. You can upload a design file with such joins, but they will be overwritten with equi-joins if you open the design in the Domain Designer. Join expressions with several boolean clauses are not supported in the Domain Design either. You can sometimes replace them with filters on tables in the join.

145


The attributes of the field element have a different meaning when defining a calculated field:dataSetExpression – Expression which calculates a value based on other columns. The syntax for the expression, including how to reference columns, is documented in section 7.2, “The DomEL Syntax,” on page 150.id – User-defined name of the calculated field. The format of the id is dependent on how the calculated field appears in the design file:1.If the expression references columns in the same table:

a.The field appears in the table and the id is a simple column name.b.The field also appears in a join tree that uses the table, the id has the form table_ID.field_name.

2.When the expression references columns in different tables, the field appears only in the join tree of those tables, and the id has the form jointree_ID.field_name.

3.When the expression computes a constant value. The field appears in a table named Constant, and the id is a simple column name. Constant fields are further explained below.

type – The Java type of the value calculated by the expression, for example java.lang.String. This type must be compatible with the result of the DomEL expression and among the JDBC-compatible types listed on page 143.

A special case of a calculated field occurs when the expression does not reference any column names. The calculated field will always have the same value and is said to be a constant. In the Domain Designer, constant fields are automatically grouped in a table named Constant and may be used in other calculated fields, filters, or even as an item. Because constant fields are not dependent on any column values, they may be used in any join tree and exposed to the user along with the items from any join tree. When editing a design file, you must treat constant calculated fields in the same way.

7.1.3.5 Representing Filters in XML

Filters are defined as optional filterString elements inside of jdbcTable and jdbcQuery elements. They impose a condition on any results that will be returned for that table, query, or join tree, thereby limiting the number of rows returned when accessing the data source. Whereas other settings mainly determine which columns will be available for use in a report, a filter determines which rows when running the report.

filterString – Expression which evaluates to true or false when applied to each row of values in the data source. The expression refers to columns using their id attribute. Thus, a filter on a table or derived table refers to the simple column name, but a filter on a join tree refers to the table_ID.field_name. The full syntax for the expression is documented in section 7.2, “The DomEL Syntax,” on page 150.

For example, the following filters are defined in the example Domain on page 122:

<jdbcTable datasourceId="SugarCRMDataSource" id="accounts" tableName="accounts"><fieldList>

...<field dataSetExpression="concat( billing_address_city, ', ',

billing_address_state )" id="city_and_state" type="java.lang.String"/>...

</fieldlist></jdbcTable>...<jdbcTable datasourceId="SugarCRMDataSource" id="JoinTree_1" tableName="anything">

<fieldList>...<field dataSetExpression="concat( accounts.billing_address_city, ', ',

accounts.billing_address_state )" id="accounts.city_and_state"type="java.lang.String"/>

...</fieldlist>

</jdbcTable>

Filters defined in the Domain Designer are limited to conditions on one column or comparisons of two columns, with more complex filters created by the conjunction (logical AND) of several conditions. Other filter expressions are not supported. You can upload a design file with more complex filters, but they will be overwritten or cause errors if you open the design in the Domain Designer.

146


7.1.3.6 Representing Sets and Items in XML

Now that all the table and field IDs have been defined, we look at the definitions of sets and items that will be exposed through itemGroups and items elements at the top of the Domain design file.

The itemGroups and items elements are equivalent to the selection of sets and items on the Display tab of the Domain Designer. They create a hierarchy of sets, subsets and items and hold attributes that define all the properties available on sets and items. For a description of each possible property, see section 6.4.9, “The Properties Table,” on page 133.

The following example shows two levels of sets, with items inside each level as well as at the root, outside of any set.

itemGroups – A container for itemGroup elements.itemGroup – Represents a set. The itemGroup element may contain an itemGroups element, an items element, or both, representing its subsets and items, respectively. The attributes of itemGroup are the properties of the set it represents:

id – The unique identifier of the set among all set and item IDs. This attribute is required.label – The set’s name, visible to users of the Domain. If the label is missing, the Ad Hoc Editor will display the id.description – The optional description of the set, visible to users as a tooltip on the set name in the Ad Hoc Editor.labelId – The internationalization key for the label in the Domain’s locale bundles.descriptionId – The internationalization key for the description in the Domain’s locale bundles.

<jdbcTable datasourceId="SugarCRMDataSource" id="opportunities"tableName="opportunities">

<fieldList>...<field id="opportunity_type" type="java.lang.String"/>

</fieldList><filterString>opportunity_type == 'Existing Business'</filterString>

</jdbcTable><jdbcQuery datasourceId="SugarCRMDataSource" id="p1cases">

<fieldList>...<field id="status" type="java.lang.String"/>

</fieldList><filterString>status != 'closed'</filterString><query>...</query>

</jdbcQuery>

<itemGroups><itemGroup label="outerset" ... >

<itemGroups><itemGroup label="innerset" ... >

<items><item label="innersetitem1" ... /><item label="innersetitem2" ... />

</items></itemGroup>

</itemGroups><items>

<item label="outersetitem1" ... /><item label="outersetitem2" ... />

</items></itemGroup>

</itemGroups><items>

<item label="outsideitem1" ... /><item label="outsideitem2" ... />

</items>

147


resourceId – A reference to the table on which the set is based. This attribute is required, but it has no meaning on a set and is not significant in the design.

When an internationalization key is defined for the label or description, the label or description will be replaced with the value given by the key in the local bundle corresponding to the user’s locale. For more information, see section 7.5, “Locale Bundles,” on page 161.items – A container for item elements.item – Represents an item. The attributes of item are the properties of the item it represents:

id – The unique identifier of the item among all set and item IDs. This attribute is required.label – The item’s name, visible to users. If the label is missing, the Ad Hoc Editor will display the id.description – The optional description of the item, visible as a tooltip on the item name in the Ad Hoc Editor.labelId – The internationalization key for the label in the Domain’s locale bundles.descriptionId – The internationalization key for the description in the Domain’s locale bundles.resourceId – A reference to the column on which the item is based. This attribute is required because it defines the connection between what the user sees and the corresponding data in the data source. The resourceId has the form table_ID.field_ID. When the item refers to a column in a join tree, the resourceID corresponds to jointree_ID.table_ID.field_name because the field ID in a join tree includes the table ID.defaultMask – A representation of the default data format to use when this item is included in a report. The possible values for the defaultMask depend on the type attribute of the column referenced by the resourceId. See the table below.defaultAgg – The name of the default summary function (also called aggregation) to use when this item is included in a report. The possible values for the defaultAgg depend on the type attribute of the column referenced by the resourceId. The following table gives the possible data formats and summary functions based on the column type. The appearance columns show the equivalent setting in the properties table of the Display tab:

The following example shows the use of the itemGroup and item elements to represent the sets and items from section 6.2, “Example of Creating a Domain,” on page 117. The design file was exported from the Domain Designer.

Field Type

Default Data Formats Default Summary Functions

Attribute Value Appearance Attribute Value Appearance

Integer #,##00$#,##0;($#,##0)#,##0;(#,##0)

-1,234-1234($1,234)(1234)

Highest

Lowest

Average

Sum

DistinctCount

Count

MaximumMinimumAverageSumDistinct CountCount All

Double #,##0.000$#,##0.00;($#,##0.00)$#,##0;($#,##0)

-1,234.56-1234($1,234.56)($1,234)

Date short,hidemedium,hidelong,hidemedium,medium

3/31/09Mar 31, 2009March 31, 2009Mar 31, 2009 23:59:59

DistinctCount Count

Distinct CountCount All

All others Not allowed

148


Labels and descriptions may contain any characters, but the ID property value of both itemGroup and item elements must be alphanumeric and not start with a digit.

<itemGroups>...<itemGroup id="users1" label="Account Rep" description="Primary account

representative" labelId="" descriptionId="" resourceId="JoinTree_1"><items>

<item id="first_name" label="First Name" description="Given name"labelId="" descriptionId="" resourceId="JoinTree_1.users1.first_name"/>

<item id="last_name" label="Last Name" description="Surname or family name"labelId="" descriptionId="" resourceId="JoinTree_1.users1.last_name"/>

</items></itemGroup><itemGroup id="opportunities" label="Opportunity" description="Sales opportunity"

labelId="" descriptionId="" resourceId="JoinTree_1"><items>

<item id="date_entered1" label="Date" description="Date opportunity opened"labelId="" descriptionId="" defaultMask="short,hide"resourceId="JoinTree_1.opportunities.date_entered"/>

<item id="amount" label="Amount" description="Estimated contract Amount"labelId="" descriptionId="" defaultMask="$#,##0;($#,##0)"defaultAgg="Average" resourceId="JoinTree_1.opportunities.amount"/>

<item id="probability" label="Probability" description="Chance of closing thecontract" labelId="" descriptionId=""resourceId="JoinTree_1.opportunities.probability"/>

<item id="description1" label="Description" description="Description ofopportunity" labelId="" descriptionId=""resourceId="JoinTree_1.opportunities.description"/>

<item id="lead_source" label="Lead Source" description="Lead Source" labelId=""descriptionId="" resourceId="JoinTree_1.opportunities.lead_source"/>

<item id="sales_stage" label="Sales Stage" description="Sales Stage" labelId=""descriptionId="" resourceId="JoinTree_1.opportunities.sales_stage"/>

</items></itemGroup><itemGroup id="p1cases" label="P1 Case" description="High priority (P1) support

case" labelId="" descriptionId="" resourceId="JoinTree_1"><items>

<item id="case_number" label="Case" description="Case number" labelId=""descriptionId="" resourceId="JoinTree_1.p1cases.case_number"/>

<item id="date_entered2" label="Date" description="Date case opened" labelId=""descriptionId="" resourceId="JoinTree_1.p1cases.date_entered"/>

<item id="name2" label="Summary" description="Name or summary of case"labelId="" descriptionId="" resourceId="JoinTree_1.p1cases.name"/>

<item id="description2" label="Description" description="Detailed descriptionof the case" labelId="" descriptionId=""resourceId="JoinTree_1.p1cases.description"/>

<item id="resolution" label="Resolution" description="Description of the caseresolution" labelId="" descriptionId=""resourceId="JoinTree_1.p1cases.resolution"/>

<item id="status" label="Status" description="Current case status" labelId=""descriptionId="" resourceId="JoinTree_1.p1cases.status"/>

</items></itemGroup>...

</itemGroups>

149


7.1.4 Uploading a Design File to a DomainOnce you have modified an XML design file, you can upload it through the Edit Domain dialog. Alternatively, you can create a new Domain based on a modified file or even on a design file created from scratch.

To upload an XML design file:1. Log in to JasperServer as an administrator and select View > Repository.2. Browse or search the repository to locate the Domain, typically by setting the Domain filter.

If you want to create a new domain, locate the folder where you want to place it.3. To update an existing Domain, right-click the Domain and select Edit from the context-menu.

To create a new Domain, right-click the folder and select Add Resource > Domain from the context menu.The Domain appears in the Data and Design page of the Edit Domain or Add New Domain dialog. If you are creating a new Domain, you must select a data source before you can proceed.

4. Select the Upload tab under the Design heading, then click Browse to find and upload your XML design file.

JasperServer validates the uploaded XML file. If there are syntax or semantic errors, the current design is not replaced. You can make changes to the XML file and upload it again until there are no errors.

5. If you used only supported features in your design file, verify the uploaded Domain design by selecting the Edit tab and clicking Launch Domain Designer. Make sure the settings you made in the XML file appear as expected on the various tabs of the Domain Designer. If there are any errors or inconsistencies, you should make changes to the XML file, upload it again, and verify it again. The results of editing a design in the Domain Designer based on inconsistent XML file are unpredictable. If you cannot resolve the error or inconsistencies, you should click Cancel on the Data and Design page so that the uploaded design is not saved.Once the design appears correctly in the Domain Designer, you may make further modifications on any of the tabs.

6. Click Save to update the Domain in the repository.7. If you modified an existing Domain, you must clear your Ad Hoc cache of all queries based on the Domain. This will

remove any data that was based on the old instance of your Domain and avoid inconsistencies in new reports. For instructions, see the JasperServer Administrator Guide.

7.2 The DomEL SyntaxVarious components of Domain need to compute values based on some expression involving constants, field values, and environment variables. The Domain Expression Language (DomEL) was created to fulfill this need. Currently, the following features in XML design files are expressed in DomEL:

The on and where clauses of derived tablesThe on clause of join statementsCalculated fieldsFilter expressions in Domains and Domain topics (equivalent to where clauses)Row-level security (see section 7.4, “The Domain Security File,” on page 155)

A DomEL expression is a shorthand way of writing a complex query. When processing a report based on a Domain, JasperServer interprets DomEL expressions to generate parts of the SQL expression that will perform the desired query. Depending on the data policy, the augmented SQL with either be passed to the data source, or JasperServer will perform a simpler query and apply the DomEL expressions to the full data set in memory.

The design file overwrites any existing design without prompting. If you made a mistake or upload the wrong file, click Cancel on the Data and Design page and start over.

If you intentionally use syntax in your design file that Domain Designer does not support, do not launch the Domain Designer after uploading the file. The Domain Designer can have unpredictable results with some XML designs it does not support.

150


7.2.1 DatatypesThe following simple datatypes may be declared as constants, used in expressions, and returned as values:

The following composite datatypes may be declared as constants and used with the in set or in range operator. The values in these composite types are not necessarily constant, they could be determined by field values:

7.2.2 Field ReferencesDomEL expressions are stored in the Domain design and interpreted when JasperServer prepares to run a query to retrieve data from the data source. Therefore, all references to field values in an expression are based on the IDs given in the Domain design. Field references have the following format, depending on where the expression appears:

Simple Type Description Example of Constant

boolean Expressions such as comparison operators return boolean values, but true and false constants are undefined and cannot be used.

none

integer Whole numbers. 123 or -123

decimal Floating point numbers. Decimal separator must be a period (.); other separators such as comma (,) are not supported.

123.45 or -123.45

string Character string entered with single quotes ('); double quotes (") are not supported.

'hello world'

date ANSI standard date. d'2009-03-31' orDate('2009-03-31')

timestamp ANSI standard date and time. ts'2009-03-31 23:59:59' orTimeStamp('2009-03-31 23:59:59')

Composite Type

Description Example

set Contains any number of any simple type above. (1, 2, 3)('apples','oranges')

range Inclusive range applicable to numbers and dates, including fields that are number or date types.

(0:12) or (0.0:12.34)(d'2009-01-01':d'2009-12-31')(limit_min:limit_max)

Appears In Field Reference Explanation

Derived table table_ID.field_name The SQL query that defines a derived table can refer to any previously defined table or derived table in the Domain. Therefore, you must include the table ID.

Join expression table_alias.field_name Within a join expression, tables are given alias names that must be used. Even though join expressions may appear in separate joinedDatasetRef elements, the alias declared in each one can be used in any subsequent one.

Calculated field on a table or derived table

field_name Calculated fields can only appear on a table if they refer exclusively to fields of the table, in which case no table ID is needed. However, the table ID is not forbidden, and the Domain Designer sometimes includes it.

151


7.2.3 Operators and FunctionsDomEL provides the following operators, listed in order of precedence. Operators higher in this list will be evaluated before operators lower in the list.

DomEL also defines the following operations as functions:

You may also use SQL functions in a DomEL expression under limited circumstances:They must be supported by your database. See your vendor documentation for available functions and their syntax.They must follow the convention of comma-separated parameters. For example, you can use TRIM(person.name), but not TRIM('Jr' FROM person.name)

The type of the return values must be appropriate, either within the expression or for the type of the calculated field.The SQL context must be appropriate for the functions. For example, you cannot use aggregation functions such as COUNT in a calculated field because there is no GROUP BY clause.

Calculated field on a join tree.

table_ID.field_name Calculated fields declared in join trees refer to fields prefixed with their table ID.

Filter on a table or derived table

field_name Filters that are evaluated within the table or derived table do not need the table ID.

Filter on a join tree table_ID.field_name Filters that refer to fields in separate tables of the join tree need to use the table ID on each field name.

Operator Syntax Description

multiply, divide i * j / k Arithmetic operators for numeric types only. Parentheses for grouping are not supported.

add, subtract i + j - k

equal i == j Comparison operators for string, numeric, and date types.

not equal i != j

less than i < j Comparison operators for numeric and date types only.

less than or equal i <= j

greater than i > j

greater than or equal i >= j

in set i in ('apples','oranges') Sets can be of any type.

in range i in (j:k) Ranges must be numeric or date types.

not not ( i ) Boolean operators. Parentheses are required for not and may be used for grouping.

and i and j and k

or i or j or k

Function Syntax Description

startsWith startsWith(i, 'prefix') Comparison operators for strings. To test string equality, use i in ('string').

endsWith endsWith(j, 'suffix')

contains contains(k, 'substring')

concat concat(i, ' and ', j, ...) Returns the string of all parameters concatenated.

Appears In Field Reference Explanation

152


Except for the comma-separated parameter pattern, the DomEL validation cannot enforce these criteria. You must ensure that any SQL functions meet these criteria, otherwise your expression will cause errors when using the Domain to create a report.

Complex expressions are written by grouping any of the operators or functions above. Parentheses () may be used for grouping boolean operators, but arithmetic expressions that rely on parentheses are not supported. To compute complex arithmetic expressions, you may need to define several expressions as separate calculated fields, and then reference them in a simpler expression in another calculated field.

The following examples show expressions suitable for filters. This first one selects only stores in western states of the US:s1.store_country in ('USA') and s1.store_state in ('WA', 'OR', 'CA', 'NV')

The following filter expression uses a date range:s1.first_opened_date in ( Date( '2000-01-01' ) : Date( '2004-12-31' )) and not( s1.closed )

As shown in these examples, field values are often compared to constant values such as 'USA'. Therefore, the author of the design file must ensure that values used in a DomEL expression exist in the data source. Otherwise, a wrong value might go undetected and impact the quality of data in reports based on the Domain. The Domain Designer determines values for comparison by accessing the data source, so if you export a design file, you can use the values it has found. Another way to reduce errors and also support future data changes is to use more general expressions such as:

s1.store_country in ('US', 'USA', 'United States')

7.2.4 Return ValueDomEL expressions are used in different contexts for different purposes. The expected return type depends on where the expression appears:

7.3 Resources of a DomainThe two optional components of a Domain are also called resources because they are defined by uploaded files:

A single security file. Defines row and column-level access to data selected by the Domain.Any number of locale bundles. Provide internationalized labels for the sets and items of the Domain design.

These files are uploaded and managed on the Resources page of the Edit Domain or Add New Domain dialog. This section describes how to upload and replace Domain resources. For more information about the syntax of resource files, see sections 7.4, “The Domain Security File,” on page 155 and 7.5, “Locale Bundles,” on page 161.

Appears In Expected Return Type Explanation

Derived Table SQL query with boolean expressions

A derived table is defined by an SQL expression that contains DomEL expressions. The join on clause may contain boolean comparisons and the where clause may contain filters, both of which are described below.

Join expression boolean Within a join expression, the on clause contains a comparison of fields from each table that has a boolean result. The on clause may also contain other DomEL expressions logically associated with and or or to create a complex join condition (see warning on page 144).

Calculated field any type The expression must evaluate to a type that is compatible with the SQL type declared in the Domain Designer or in the design file. For example, if the declared type is java.lang.Float, the expression must compute a decimal value.

Filter boolean Filters must be true or false overall. When there are several conditions, they must be logically associated with and or or (currently, only and is supported in the Domain Designer).

153


To upload or manage a security file and locale bundles for a Domain:1. Log in to JasperServer as an administrator and select View > Repository.2. Search or browse the repository to locate the Domain, typically by setting the Domain filter.3. Right-click an existing Domain and select Edit from the context-menu.

The Domain appears in the Data and Design page of the Edit Domain dialog.4. Click Resources at the top of the page or Next at the bottom.

5. Click Add Security or Add Locale Bundle to upload a security file or locale bundle to the Domain.There can only be one security file but any number of locale bundles. When a security file exists, the Add Security text is disabled. See step 9 to replace an existing security file.A window appears in which you can select the resource.

6. Resources can be uploaded from local files or from objects in the repository. Click the Local File or Repository tab and then Browse to select a file or repository object.When browsing the repository, you will see only XML files or locale bundle objects in the repository. For the security file, select an XML file created explicitly as a security file. When selected, the XML file in the repository is referenced by the Domain, unlike a local file that is uploaded directly into the Domain.

7. Click OK to upload the file and add it to the list of current resources.JasperServer validates the file to make sure it matches the format of a security file or locale bundle. If the file type is not recognized or there is a syntax error, the file is not added to the list of resources and you must select another file or click Cancel.

Figure 7-1 Blank Resources Page in the Add New Domain Dialog

Figure 7-2 Add Security File Dialog

The repository manager will warn you if you attempt to delete a resource that is referenced by a Domain, but it will not warn you if you replace it with a different file. When you store resource files in the repository, you must ensure that any updates to the files are compatible with the Domains that reference them.

154


8. Repeat steps 5 through 7 to upload one security file and any number of locale bundles.The Resources page shows the list of all uploaded files.

9. To manage the uploaded resources, select a file and click one of the following buttons on the Resources page:Edit – Replaces the selected file with a different one uploaded from a file or from the repository.Delete – Removes the selected file from the Domain.Download – Lets you save the security file or locale bundle to a local file.For example, if you add an item to you Domain after creating your locale bundles, you will need to add its label and description keys to each bundle. Download each of the locale bundles in your Domain, edit each file to add the new keys, then upload each file to replace the corresponding locale bundle. You might also want to define access permissions for the new item by downloading, modifying, and uploading the security file as well.

10. If you modified an existing Domain, you must clear your Ad Hoc cache of all queries based on the Domain. This will remove any data that was based on the old instance of your Domain and avoid inconsistencies in new reports. For instructions, see the JasperServer Administrator Guide.

7.4 The Domain Security FileThe security file defines permissions to control access to Domain data on the basis of user names and roles existing in JasperServer. When creating or running a report based on a Domain, the user name and roles are checked against the permissions in the security file. Permissions can be set separately on the data’s columns and rows.

Security on columns is defined by permissions on the sets and items of the Domain, corresponding to columns in the data source. For example, only certain users might be able to see sensitive employee information such as a Social Security Number. Security on rows is defined by permissions on the data values, for example a manager might only be allowed to see the salary column of employees whose manager field equals the manager’s employee number.

The IDs of tables, columns, sets and items that appear in the design are referenced by the security file. In Domains, columns display the items in the Domain; rows display the values of each item. Column security is defined on itemGroupId and itemId; row security is defined on resourceId.

A user can only see results where he has both column- and row-level access. For instance, in a certain Domain, user David has access to columns A-F and rows 1-6. Tomas has access to columns B-C and rows 1-3. Anita has access to columns C-E and rows 2-5. When the users run reports from the Domain, they get different results. David sees data in cells where columns A-F

Figure 7-3 Resources Page for Supermart Domain in the Edit Domain Dialog

155


and rows 1-6 intersect. Tomas sees data only where columns B-C and rows 1-3 intersect. Anita sees data only where columns C-E and rows 2-5 intersect.

For a given query on the data source, the security definition finds the access grants and determines his access rights, determined first for item groups and items, then for resources. When the query is passed to the data source and the report is run, the grants are applied as filters on the report’s columns and rows. Security that is defined on the physical layer applies to all content in the presentation layer. Security that is defined on a join applies only to the presentation layer content that is specific to the join.

When a user is designing a report in the Ad Hoc Editor, he sees only the columns to which he has access. When the report runs, portions to which the user has no access will be blank.

Access grants take a principalExpression that evaluates the principal in authentication objects created in the Acegi security framework (http://www.jasperforge.org). The standard expression is

<principalExpression>authentication.getPrincipal().getRoles().any{ it.getRoleName() in ['ANY_SUPPORTED_ROLE'] }</principalExpression>

The expression gets the current authentication object and determines the access privileges of the principal in the object. Then, from JasperServer, it gets the user and roles associated with the object. Finally, it evaluates the roles for the specified role. The access grants are applied to the role.

The expression evaluates to<principalExpression>authentication.principal.roles.roleName in ('ANY_SUPPORTED_ROLE')</principalExpression>

While the standard principal expression tests for a given role, an expression can test for any object in the principal. For example, this expression tests for attribute A:

<principalExpression>authentication.getPrincipal().getAttributes().any{ it.getAttributeA() in ['ANY_SUPPORTED_ROLE'] }

</principalExpression>

The scripting language for principalExpression is Groovy (http://groovy.codehaus.org).

All access grants for a Domain are defined in a single security file that is attached to the Domain as a resource, as described in section 7.3, “Resources of a Domain,” on page 153. The default access is granted.

When creating a security file, be sure to use the IDs of items and groups as they are defined in the Domain design file exported from the Domain Designer. For more information, see section 7.1.2, “Working With a Design File,” on page 140. If you modify your Domain, you should also export the design file and update the security file with any IDs that have changed.

Item A Item B Item C Item D Item E Item F

1 David DavidTomas

DavidTomas

David David David

2 David DavidTomas

DavidTomasAnita

David David David

3 David DavidTomas

DavidTomasAnita

DavidAnita

DavidAnita

David

4 David David DavidAnita

DavidAnita

DavidAnita

David

5 David David DavidAnita

DavidAnita

DavidAnita

David

6 David David David David David David

156

http://www.jasperforge.org

http://groovy.codehaus.org/


A typical security file has the following structure:

7.4.1 Row-Level SecurityRow-level security is specified in resourceAccessGrants. For each dataset from which data is returned by a query in the design file, a resourceAccessGrantList specifies the rows to which a user has access. Each grant is defined in a resourceAccessGrant that contains a principalExpression and a filterExpression.

A resourceAccessGrant must be defined for a joined resource if any query in the security definition has at least one item from the resource, even if that query does not include the related dataset.

Row-level security applies whenever access to a secured resource is requested, even if the request is indirect. For instance, a column in the Region table might be joined to a column in the Sales table. User Tomas has access to Region but not Sales. Tomas’s report uses columns from Region but he cannot see them because he does not have access to Sales.

<securityDefinition xmlns="http://www.jaspersoft.com/2007/SL/XMLSchema"version="1.0" itemGroupDefaultAccess="granted">

<resourceAccessGrants> 

<resourceAccessGrantList id="expense_join_resource_access_grant" label="aLabel" resourceId="expense_join">

<resourceAccessGrants>

<resourceAccessGrant id="expense_join_ROLE_SUPERMART_MANAGER_store_row_grant">

<principalExpression>authentication.getPrincipal().getRoles().any{ it.getRoleName() in ['ROLE_SUPERMART_MANAGER'] }</principalExpression>

<filterExpression>s.store_country in ('USA') and s.store_state in ('CA')</filterExpression>

</resourceAccessGrant>

...

</resourceAccessGrants>

</resourceAccessGrantList>

...


<itemGroupAccessGrants> 

<itemGroupAccessGrantList id="expense_join_item_group_access_grant_group" label="aLabel" itemGroupId="expense_join" defaultAccess="denied">

<itemGroupAccessGrants>

<itemGroupAccessGrant id="expense_join_super_user_item_group_grant" access="granted">

<principalExpression>authentication.getPrincipal().getRoles().any{ it.getRoleName() in ['ROLE_ADMINISTRATOR'] }</principalExpression>

</itemGroupAccessGrant>

...

</itemGroupAccessGrants>

</itemGroupAccessGrantList>

...

</itemGroupAccessGrants>

</securityDefinition>

157


Row-level security is defined as follows:

Elements of resourceAccessGrants are:resourceAccessGrantList. List of grants for one dataset in the Domain.

resourceAccessGrant. Grant in the dataset for a specific case, such as a user role or profile attribute.principalExpression. Evaluation of the authentication object and user to determine the role to be granted access.filterExpression. Filter on the dataset; determines the rows to which access is granted. Filters are applied to resource IDs. See the section 7.2, “The DomEL Syntax,” on page 150 for examples of valid filter expressions.

<resourceAccessGrants> 

<resourceAccessGrantList id="expense_join_resource_access_grant" label="aLabel" resourceId="expense_join">


<resourceAccessGrant id="expense_join_ROLE_SUPERMART_MANAGER_store_row_grant">


<filterExpression>s.store_country in ('USA') and s.store_state in ('CA')

</filterExpression>


<resourceAccessGrant id="account_ROLE_SUPERMART_MANAGER_account_row_grant" orMultipleExpressions="true">


<filterExpression>s.store_number == 0</filterExpression>


<resourceAccessGrant id="account_ROLE_SUPERMART_MANAGER_account_row_grant2" orMultipleExpressions="true">


<filterExpression>s.store_number == 24</filterExpression>




<resourceAccessGrantList id="account_resource_access_grant" label="aLabel" resourceId="account">


<resourceAccessGrant id="account_resource_super_user_row_grant">

<principalExpression>authentication.getPrincipal().getRoles().any{ it.getRoleName() in ['ROLE_ADMINISTRATOR'] }</principalExpression>


<resourceAccessGrant id="account_ROLE_SUPERMART_MANAGER_row_grant">


<filterExpression>account_type == 'Expense'</filterExpression>





158


7.4.2 Column-Level SecurityColumn-level security is specified in itemGroupAccessGrants. An itemGroupAccessGrantList defines default access to one item group. Within the group, access is granted by user role in itemGroupAccessGrants. Access to items within an item group can be specified by itemAccessGrants.

Column-level security passes from parent object to child object unless specified otherwise: If access is unspecified for an object, the access of the parent object applies. If the unspecified object is an item in an item group, the item group’s access applies.If the unspecified object is an item in an item group that is nested in another item group, the access of the nearest parent item group applies to the item. If the nearest parent group’s access is also unspecified, that group takes its access from its parent group and passes it to the item. In this case (specified item group > unspecified item group > unspecified item), access for the item cannot be specified in an item-level grant. If access is specified for an item group but there is no item group principal expression matching the current user, the user has the item group’s default access, not the item group’s specified access. If a matching item group principal expression does exist, the user’s access to items for which access is specified will be as specified. Access to other items will be the item group’s specified access.If multiple item group principal expressions match the user (such as one expression for the user and one for his role), their access grants are combined, or ANDed, in a simple series. As a result, one denied statement overrides multiple granted statements.

Column-level security is defined as follows:

<itemGroupAccessGrants> <itemGroupAccessGrantList id="expense_join_item_group_access_grant_group" label="aLabel" itemGroupId="expense_join" defaultAccess="denied"><itemGroupAccessGrants><itemGroupAccessGrant id="expense_join_super_user_item_group_grant" access="granted"><principalExpression>authentication.getPrincipal().getRoles().any{ it.getRoleName() in ['ROLE_ADMINISTRATOR'] }</principalExpression>

</itemGroupAccessGrant><itemGroupAccessGrant id="ROLE_SUPERMART_MANAGER_item_group_access_grant" access="granted"><principalExpression>authentication.getPrincipal().getRoles().any{ it.getRoleName() in ['ROLE_SUPERMART_MANAGER'] }</principalExpression>

<itemAccessGrantList id="expense_join_ROLE_SUPERMART_MANAGER_item_grant" defaultAccess="denied"><itemAccessGrants><itemAccessGrant id="itemAccessGrant1" itemId="ej_expense_fact_exp_date" access="granted" />

</itemAccessGrants></itemAccessGrantList>

</itemGroupAccessGrant></itemGroupAccessGrants>

</itemGroupAccessGrantList><itemGroupAccessGrantList id="expense_join_store_item_group_access_grant_group" label="aLabel" itemGroupId="expense_join_store" defaultAccess="denied"><itemGroupAccessGrants><itemGroupAccessGrant id="expense_join_store_super_user_item_group_grant" access="granted"><principalExpression>authentication.getPrincipal().getRoles().any{ it.getRoleName() in ['ROLE_ADMINISTRATOR'] }</principalExpression>

</itemGroupAccessGrant><itemGroupAccessGrant id="ROLE_SUPERMART_MANAGER_store_item_group_access_grant" access="granted">

159


Elements of itemGroupAccessGrants are:itemGroupAccessGrantList. List of access grants to one item group. Specifies default access to the item group and all items in the group. If you want to restrict access to items outside of any group or set, create an itemGroupAccessGrantList for them where the id of the group is "".

itemGroupAccessGrant. Specifies access to the item group for one user role.principalExpression. Evaluation of the authentication object and user to determine the role to be granted or denied access.

itemAccessGrantList. List of access grants to items in the item group. Specifies default access to the items. Overrides default in itemGroupAccessGrantList.

itemAccessGrant. Specifies access to one item.

In the above example, the progression of column access grants is:Deny access to everyone. For each item group:

Grant group access to administrator roles. Grant group access to additional roles.For each additional role, deny access to specific items or, alternatively, deny access to all group items, then grant access to specific items.

Access is denied to everyone initially. Otherwise, all users would have complete access. Next, access to each item group is granted for administrator roles.

Next, access is defined for the SuperMart manager role. First, access is granted to each item group even though the access may be limited eventually. If access is not granted at the group level, the SuperMart manager will have no access at all. Then, access to all items in the group is denied, followed by grants to specific items.

An alternative way to restrict access is to simply deny it on specific items. However, this method is not as secure as denying access to all items then granting access to some. The latter requires the programmer to specifically identify each item to which the role has access, which is more secure.

By default, all grants for a given role are ANDed. The ANDed series can be modified by an OR expression (orMultipleExpressions="true"). For instance, the following grants are implemented as A and B and C:


<itemAccessGrantList id="expense_join_ROLE_SUPERMART_MANAGER_store_item_grant" defaultAccess="denied"><itemAccessGrants><itemAccessGrant id="itemAccessGrant3" itemId="ej_store_store_type" access="granted" />

<itemAccessGrant id="itemAccessGrant4" itemId="ej_store_region_id" access="granted" />

<itemAccessGrant id="itemAccessGrant5" itemId="ej_store_store_name" access="granted" />

<itemAccessGrant id="itemAccessGrant6" itemId="ej_store_store_number" access="granted" />

<itemAccessGrant id="itemAccessGrant7" itemId="ej_expense_fact_exp_date" access="granted" />

<itemAccessGrant id="itemAccessGrant8" itemId="ej_expense_fact_amount" access="granted" />

</itemAccessGrants></itemAccessGrantList>

</itemGroupAccessGrant></itemGroupAccessGrants>

</itemGroupAccessGrantList></itemGroupAccessGrants>

160


<resourceAccessGrant id="A"><resourceAccessGrant id="B">

<resourceAccessGrant id="C">;

while these grants are implemented as (A or B) and C: <resourceAccessGrant id="A"><resourceAccessGrant id="B" orMultipleExpressions="true">

<resourceAccessGrant id="C">

The OR expression can be applied in grants for items and item groups as well as resources.

7.5 Locale BundlesA locale bundle is a set of properties files used in localizing software. The files contain other-language versions of the labels and messages that are displayed to users. When a user’s operating environment specifies a locale, JasperServer looks for the corresponding locale bundle and uses the labels and messages it contains. The JasperServer interface is already internationalized, and Domains make reports internationalizable so that users can create and view reports in their language.

A locale bundle for a Domain consists of a single file containing all the internationalization keys for the sets and items in the Domain. Each key is associated with the text for the label or description in the language of the target locale. The name of the file includes the target locale, so JasperServer automatically associates it with the user’s locale when needed.

When a Domain with locale bundles is used to create or run a report, JasperServer resolves each label to display as follows:JasperServer looks for a bundle corresponding to the current locale and for the key corresponding to the label. If both exist, JasperServer displays the text associated with the key; if the bundle or key does not exist, thenJasperServer looks for the same key in a default bundle among the resources. If these exist, it displays the text associated with the key in the default bundle; if the default bundle or key does not exist, thenIt displays the text of the label property defined in the Domain design; if no label is defined, thenIt displays the value of the id property.

Descriptions are localized in the same manner, except they are left blank if there is no locale bundle, default bundle, or description property defined.

There are several strategies for managing your locale bundles. Based on the search algorithm above and your localization needs, you could have one of the following scenarios:

You do not have any localization needs at the time you create your Domain. You give all labels and descriptions a clear and complete text within the design, and you leave the key names undefined. As your enterprise grows, users in another country need to create reports based on your Domain. To create localized text for those users, edit your Domain design to define the internationalization keys, then create the locale bundle. You can create locale bundles incrementally each time you have users who need a new language. Users in your home country who do not specify a locale will still see the labels and description in the original Domain design.You want to create your Domain tailored to a multilingual environment where reports need to be localized for each user’s specified locale. In this case, you do not specify any labels or descriptions in your Domain design, only the internationalization keys. Then you create a default locale bundle that gives the clear and complete text of every label and description in your preferred language. In this way, all user-visible text for your Domain is in the standard format of a locale bundle, and you can use specialized software or translation services to create all the locale bundles you need. In case a label or description is left untranslated, users will see the text of the default locale bundle.

Language Locale Filename Sample Contents

English default ExampleDomain.propertiesACCOUNTS.NAME.LABEL=Customer

ACCOUNTS.NAME.DESCR=Name of Customer

French fr ExampleDomain_fr.propertiesACCOUNTS.NAME.LABEL=Client

ACCOUNTS.NAME.DESCR=Nom du client

161


7.5.1 Defining the Internationalization KeysIn the Domain Designer, the name of the internationalization keys are defined by the Label ID and Descr. ID properties on each set and item defined on the Display tab. By default, these properties are blank. You may name the keys in any way you wish, as long as each key is unique among all keys within the Domain.

To automate this process, use the Generate Bundle Stub icon in the menu bar of the Domain Designer. This function performs two tasks:

It automatically generates all the key names. You have the option of generating only the label keys, only the description keys, both, or neither. When you click OK, the generated key names will be added to all the blank Label ID and Descr. ID properties; any keys that already exist will not be modified. In order to guarantee uniqueness, the generated key names have the following format:

SET_ID.LABELSET_ID.DESCR

SET_ID.ITEM_ID.LABEL

SET_ID.ITEM_ID.DESCR

It outputs a locale bundle stub. This is a properties file in the proper format containing all the defined keys, ready for translation. The locale bundle stub is further explained in the next section.

In the design file, the name of the keys are given by the labelId and descriptionId attributes on each itemGroup and item element. If these attributes are missing or defined with an empty value (""), the keys are not defined. To define the keys, give these attributes a value that is unique among all the keys. If you have many sets and items, it may be easier to upload the design file in a Domain and open it in the Domain Designer. You can then generate the keys automatically, export the bundle stub as explained above, and export the XML design file that now contains the generated keys.

7.5.2 Creating Locale Bundle FilesA locale bundle for a Domain is a Java properties file where each property name is a unique internationalization key from one of the labels or descriptions in the design. The value of each property is the text for the label or description in the target language. The name of the file identifies the locale in the form <any_name>_<locale>.properties, where <locale> is any Java-compliant locale identifier, for example fr or fr_CA. If the _<locale> part of the file name is omitted, the file designates the strings for the default locale.

Usually, the set of keys is identical in the properties file of each locale bundle, but this is not necessary. The text for a given key in a given locale is determined by the algorithm given on page 161.

Often, it is simplest to create the properties files from the stub exported by the Domain Designer. Whether you have created your design in the Domain Designer or in an external file uploaded to the Domain Designer, use the Generate Bundle Stub

icon in the menu bar to export a blank properties file. Optionally, you may generate any missing keys, as described in the previous section.

Figure 7-4 Locale Bundle Stub Options Dialog

If your design file does not load properly in the Domain Designer, you will not be able to use the exported design file. In this case, do not overwrite your design file, but save the exported file to another name and attempt to merge in the generated keys.

162


The following example shows part of the properties file output for the Domain created in section 6.2, “Example of Creating a Domain,” on page 117. All of the internationalization keys were generated automatically as well. As the example shows, sets and items in the bundle stub appear in the same order as on the Display tab of the Domain Designer:

The syntax for the properties file is the same as for Java properties files. Generally, everything after the = symbol is part of the translated text. 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 é). The following example shows the French translation for the properties file shown above, including the UTF-8 code for accented characters and other symbols.

Once you have the properties file for your first locale, you can simply copy the file and change the _<locale> designator to begin translation of another locale bundle. A best practice is to save a blank properties file or the default locale bundle as a

ACCOUNTS.LABEL=ACCOUNTS.DESCR=ACCOUNTS.NAME.LABEL=ACCOUNTS.NAME.DESCR=ACCOUNTS.ACCOUNT_TYPE.LABEL=ACCOUNTS.ACCOUNT_TYPE.DESCR=ACCOUNTS.INDUSTRY.LABEL=ACCOUNTS.INDUSTRY.DESCR=ACCOUNTS.ANNUAL_REVENUE.LABEL=ACCOUNTS.ANNUAL_REVENUE.DESCR=ACCOUNTS.EMPLOYEES.LABEL=ACCOUNTS.EMPLOYEES.DESCR=ACCOUNTS.CITY_AND_STATE.LABEL=ACCOUNTS.CITY_AND_STATE.DESCR=USERS1.LABEL=USERS1.DESCR=USERS1.FIRST_NAME.LABEL=USERS1.FIRST_NAME.DESCR=USERS1.LAST_NAME.LABEL=USERS1.LAST_NAME.DESCR=...

ACCOUNTS.LABEL=ComptesACCOUNTS.DESCR=D\u00e9tails des comptes clients.ACCOUNTS.NAME.LABEL=ClientACCOUNTS.NAME.DESCR=Nom du clientACCOUNTS.ACCOUNT_TYPE.LABEL=TypeACCOUNTS.ACCOUNT_TYPE.DESCR=Type du compte client.ACCOUNTS.INDUSTRY.LABEL=IndustrieACCOUNTS.INDUSTRY.DESCR=Industrie d\u2019activit\u00e9 primaire.ACCOUNTS.ANNUAL_REVENUE.LABEL=Taille par revenusACCOUNTS.ANNUAL_REVENUE.DESCR=Revenus annuels estim\u00e9s.ACCOUNTS.EMPLOYEES.LABEL=Taille du personnelACCOUNTS.EMPLOYEES.DESCR=Nombre d\u2019employ\u00e9s estim\u00e9s.ACCOUNTS.CITY_AND_STATE.LABEL=Localit\u00e9ACCOUNTS.CITY_AND_STATE.DESCR=Ville et r\u00e9gion ou \u00e9tat du client.USERS1.LABEL=ResponsableUSERS1.DESCR=Responsable du compte client.USERS1.FIRST_NAME.LABEL=Pr\u00e9nomUSERS1.FIRST_NAME.DESCR=Pr\u00e9nom usuel.USERS1.LAST_NAME.LABEL=NomUSERS1.LAST_NAME.DESCR=Nom de famille....

163

http://en.wikipedia.org/wiki/ISO/IEC_8859-1


template for future translations. Also, if you change your Domain design, you can export the locale bundle stub again and compare it to the template to find all new keys.

You can create and edit the properties file in any text editor. Certain editors provide features for editing properties files. There are also translation products that manage all of the resource bundles together, allowing you to translate in parallel and find missing keys and missing translations.

Regardless of how you edit properties files, when all translations are finished, you need to upload them as locale bundles to your Domain in order to take effect. See the procedure in section 7.3, “Resources of a Domain,” on page 153 for instructions on uploading locale bundles. Also, if you change your Domain design and need to modify your properties files, follow that same procedure to download, modify, and upload each locale bundle.

For additional information on locales and locale bundles in JasperServer, see the Localization chapter in JasperServer Administrator Guide.

164

Utilities

8 UTILITIES

This chapter contains the following sections:MessagesiReport Plug-ins

8.1 MessagesWhen an event occurs (such as an when a scheduled report returns errors), JasperServer notifies the owner of the report through an internal message. You can browse these messages to gain an understanding of report scheduling problems in JasperServer.

8.1.1 Message ListThe Messages page displays the list of events logged for the current user.

To open the Messages page:On any page, click View > Messages in the menu bar.

Use the check boxes and buttons on this page to manage your list of messages.You can view a message by clicking its name. The message opens in the Event Details page. Information there can help you troubleshoot problems with your scheduled reports, such as if a report fails because its data source is configured with incorrect credentials.

Figure 8-1 Messages Page

165


8.2 iReport Plug-insBy default, iReport includes JasperServer and Domain plug-ins. The JasperServer plug-in enables you to move reports between iReport and JasperServer. The Domain plug-in enables you create reports from Domains in the JasperServer repository.

To launch iReport:1. In Windows, click Start > All Programs > JasperServer Pro > Start iReport; or

In Linux, change to the iReport home directory and enter ./iReport.sh at the command prompt. iReport opens.

8.2.1 JasperServer Plug-inThe JasperServer plug-in requires:

iReport 3.7Java Sun JDK 1.5 or greaterJasperServer with enabled web services

To launch the JasperServer Plug-in in iReport1. Launch iReport.2. Click Window > JasperServer Repository.

A JasperServer pane appears in the upper left corner of your iReport workspace.

For more information, refer to section 5.4, “Using the JasperServer Plug-in for iReport,” on page 103.

8.2.2 Domain Plug-inThe Domain plug-in for iReport requires:

JasperServer plug-in, 3.7.iReport 3.7 JasperServer Professional or Enterprise 3.7

The Domain plug-in is included by default in the Professional version of iReport.

Figure 8-2 Event Details Page

A common cause of the error message indicating that the report failed to execute is a misconfigured mail server. The mail server must be manually configured after installation in order for users to send email notifications. For more information on mail configuration, refer to the JasperServer Administrator Guide.

166

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.

Audit Archiving

Determining the limit on saving audit results, such as limiting them to a range of dates or a total number of instances.

Audit Logging

Recording who used JasperServer to do what when. All Ad Hoc reports can be run with auditing enabled. A range of criteria can be audited and the results logged; the results can be used as input for other reports.

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).

167


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.

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.

168

Glossary

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.

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.

169


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.

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.

170

http://jpivot.sourceforge.net/

http://www.mysql.com/

Glossary

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.

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.

171


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.

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.

Web Services

A SOAP (Simple Object Access Protocol) API that enables certain features to be managed over the web without running JasperServer. The features include repository, scheduling and user administration tasks.

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.

172

http://jpivot.sourceforge.net/wcf/index.html

http://jpivot.sourceforge.net/wcf/index.html

http://www.xmla.org/

Index

INDEX

Aaccess grants

and scheduled reports 34Domain column-level 159Domain row level 157effect of grants 68, 69, 74, 155

Ad Hoc Editoravailable fields selected in Domain Topic 70calculated fields 57custom fields 57decimal places 58designing report layouts 43editing reports created in the Ad Hoc Editor 48filters 59formatting reports 48formulas 57how to use 41, 45input controls 59limits on reports 78page properties 43parametrized queries 59reports 41rounding and custom fields 58saving reports 42, 47, 49tool bar 42

Ad Hoc reportsand dashboards 24kinds 43limits 78localization 77saving 42, 47, 49

add function 57Add New Domain wizard 118adding a design file as a new Domain 150adding reports 87alphabetical ascending 54, 66alternate group 42, 61

area chart 63auto-refresh interval in dashboards 21available content 17

Bbar chart 63basic functions 57Boolean operators in Domains 69

Ccalculated fields 57cascading input controls 33, 98CGP 53, 58change fields for Domain-based reports 71chart reports

and dashboards 24compared with table and crosstab 44display options 63page size 64resizing 64sample Topic 63summarized vs. unsummarized 63theme for 112types of charts 63unique features 63

Charts Pro 29Choose Ad Hoc Data wizard 67, 76collapse group 65collapse members 66column-level security in Domains 159columns

column groups 46, 65column width 49, 66percent of column group parent 53, 58summarizing 47

controls. See input controls.count all 66creating

173


dashboards 17–24Domain security files 155Domain Topics 73reports 73, 74, 79, 87, 103

crosstab reportsadding fields 65and dashboards 24and dataset size 42collapse group 65collapse members 66column group parent 53, 58compared with table 44drill to details 66exclude 52, 66expand group 65expand members 51, 66hyperlinks 66keep only 52, 66measures 65percent of group 58pivoting 65row and column groups 65row group parent 53, 58sample size 66sample Topic 65setting data formats 66sorting 54, 66switch to column group 51, 65switch to row group 65unique features 65

custom fieldsadd 57basic functions 57date functions 57default name 58divide 57multiply 57operators 57overview 57percent of group parent 57percent of total 57rank 57renaming 58round 57special functions 57subtract 57swap fields 57

custom URL in dashboards 17, 23

Ddashboards

adding content 22adding custom URLs 17adding logos 17and Ad Hoc reports 24and available items 17

174

and custom URLs 20, 23and input controls 19, 22, 25and parameters 25and screen size 23, 24area 18auto-refresh interval 21behavior when content deleted from repository 23buttons 17containing other dashboards 22, 23creating 17–24deleting content 21, 22designer 18edit 24HTTP v. FILE protocol 23limitations 17, 25mapping input controls to URLs 20multiple selection 22, 23overview 17proportional v. fixed sizing 23refining the layout 21saving 18SuperMart dashboard 16tips for creating reports 24title 21viewing 16working with 15–25

Data and Design page 118data formats 49, 66Data page 67data policies 78data sources, access grants, and scheduled reports 34datasets 42datatypes 92, 100date functions 57design files

See also Domains.adding as a new Domain 150editing 141exporting 140filters 150itemGroups element 142items element 142joins 144Oracle schema name 141resources element 142schema element 141schemaLocation attribute 142structure 141–149uploading edited file 150version attribute 141xmlns attribute 141XSD 140

Display page 69distinct count 66divide function 57

Index

Domain Designer 118Domain plug-in

input controls 110installing 166parametrized queries 110using in iReport 108

Domain Topicsediting 76effect of access grants 68, 69, 74, 155saving 73

DomainsSee also design files.access grants and scheduled reports 34Boolean comparison operators 69defined 115defined by a new design file 150design file 139designing a Domain 117–134Domain plug-in for iReport 108, 166editing 135effect of access grants 68, 69, 74, 155exporting designs to XML files 140filtering data for a report 68filters 69Groovy 156input controls 110item sets 68, 123joins 120, 132locale bundles 161localization 161presentation and physical layers 156principal expressions 156properties files 161referential integrity 136samples 117saving as Topics. See Domain Topics.Simple Domain 117Simple Domain Topic 117SuperMart Domain 117typical uses 115using a Domain for a report 67

drill to details 66dynamic filters 59

EEdit Domain Topic wizard 76Event Details page 165exclude 52expand group 65expand members 51, 66exporting Domain designs to XML design files 140external resources 88

Ffields

changing for Domain-based reports 71

in crosstab reports 64, 65filter pane 43, 52, 59filters

compared to input controls 59filtering items in Domains 69in Domain plug-in 110in Domains 68in the Ad Hoc Editor 59, 60in Topics 59using 60

Filters page 68fixed sizing 24Flash charts 29folders 106fonts 88formats for report output 28formatting reports 48formulas 57Fusion 29

Gglossary 167Groovy 156groups

adding to crosstab reports 64expanding and collapsing 65pivoting 42switching 42, 51, 61, 65

Hhelp 9hide scroll bars 22hiding detail rows 49Home page

for end users 8icons 9

Iicons

export report output 28Home page 9

input controls 42adding 90and dashboards 17, 19, 25and parametrized queries 59cascading 33, 98check box 92, 93compared to filters 59date 95default values 30display differences in dashboards 25encouraging reuse of 25in reports run from Domain plug-in 110in the Ad Hoc Editor 42, 59limitations 25mapped to custom URLs 20, 22pop-up page 31

175


running a report with input controls 30testQuery 95text 91types 90using 59

installingDomain plug-in 166JasperServer plug-in 166

iReportadding resources 106connecting to JasperServer 103creating reports 105Domain plug-in 108, 166JRXML files 107limits on reports 78repository 105, 107running reports 108

item sets 68, 123itemGroups element in design files 141, 142items element in design files 142

JJAR files 87, 88, 113JasperAnalysis 9Job Details pages 35Jobs List page 34jobs. See scheduling reports.joins

in Domains 120, 132security 156

JRXML filesand Domain Topics 73and Topics 76external resources 88field names in 101field names in Topics 77in iReport 107to create a new report 81, 87

Kkeep only 52

Llayouts of reports 43Liferay 64line chart 63locale bundles 161locales 8, 77, 101localization of Domains 161Locate Query page 84logging in 8

MMain JRXML page 81, 87Maps Pro 29measures 65messages about system events 165Messages page 165

176

multiple v. single controls in dashboard 17multiply function 57

NNaming page 81numeric ascending and descending 54, 66

Oonline help 9Oracle

choosing schemas 125, 127, 128NVARCHAR2 127schema name in design file 141synonyms 127

Ppages

Data 67Data and Design 118Display 69Event Details 165Filters 68Home page for end users 8Input Control 31Job Details 35Jobs List 34Locate Query 84Main JRXML 81, 87Messages 165Naming 81Report 30Resource List 82Save Topic 74Topics and Domains 67

parametrized queries See also filters.adding input controls 90and dashboards 20, 25and reports 40in reports run from Domain plug-in 110in the Ad Hoc Editor 42, 59running a report with parametrized queries 30

passwords 8percent of group parent functions 57, 58percent of total function 57physical layer 156pie chart 63pivoting 42, 61, 65plug-ins

Domain 108, 166JasperServer 166

portal 64presentation layer 156presentation mode 42, 50preview 18principal expressions 156print view 17

Index

properties, in locale bundles 161proportional sizing 23, 24

Qquery resource 84

Rrank function 57recurrence

calendar recurrence 39simple recurrence 38types 36

redo 42referential integrity 136report area 46report output 42Report page 30Report Wizard 81reports

See also scheduling reports and running reports.Ad Hoc 41adding 87adding fields 46, 65adjusting column width 49, 66based on Domains 78based on JDBC data sources 78chart layout and formatting options 63creating 73, 74, 79, 87, 103, 105crosstab layout and formatting options 65crosstab vs. table and chart 43, 71designing in the Ad Hoc Editor 41designing layouts 43editing labels 47editing reports created in the Ad Hoc Editor 48effect of access grants 34, 68, 69, 74, 155export icons 28exporting report output 28Flash-enabled 29formatting 48limits 78localization 101report area 46report output 28report parameters 40row and column groups 46, 65running 27, 39, 42, 50, 108sample size 66sample Table report 45saving in the Ad Hoc Editor 42, 47, 49saving report output 28selecting styles 48setting data formats 49, 66sorting 62, 66summarizing rows and columns 47, 66table vs. crosstab and chart 43, 47, 71validating 86, 99

with input controls 30repository

in iReport 105, 107main page 10manager 117searching 10system messages 165

reset 17, 20resolution 24Resource List page 82resources

adding to iReport 106and Ad Hoc reports 77and localizations 101

resources element in design files 141, 142RGP 53, 58round function 57row-level security in Domains 157rows

percent of row group parent 53, 58row groups 46, 65summarizing 47

running reportsSee also reports and scheduling reports.example 27, 30Flash charts 29from iReport 108in the Ad Hoc Editor 42, 50in the background 39limits 78on a schedule 35

Ssample Domains 117sample files

AllAccounts.jrxml 80, 81logo.jpg 80SalesByMonth.jrxml 87SalesByMonthDetail.jrxml 87

sample reportsAccounts 28Freight 30SalesByMonth 87

sample size 66sample Topics

demo for adhoc 45foodmart data for crosstab 65Simple Domain Topic 117

Save Topic page 74scatter chart 63scheduling reports

See also reports and running reports.access grants and scheduled reports 34defining a job 35defining schedules 34editing a job 38

177


recurrence 38viewing job schedules 34

schema element in design files 141schemaLocation attribute in design files 142schemas. See design files.screen sizes 24search expression 13search field 11security files

column-level security 159effect of access grants 68, 69, 74filters 150principal expressions 156row-level security 157structure 155

select fields for Domain-based reports 71showing detail rows 49Simple Domain 117Simple Domain Topic 117single v. multiple controls in dashboard 17slice 52, 66sorting reports 42, 54, 62, 66spacer 49special content in dashboards 17, 20special functions 57standard controls in dashboards 17styles 48submit 17, 20subtract function 57summarized vs. unsummarized charts 63SuperMart 16switch to column group 51, 65switch to row group 65switching groups 42, 61

Ttable reports

adding fields 46adjusting column width 49and dashboards 24and dataset size 42column groups 46compared with crosstab and chart 43, 71designing layouts 43formatting 48hiding detail rows 49sample 45selecting styles 48setting data formats 49showing detail rows 49sorting 42, 62spacer 49summarizing rows and columns 47

text label 17themes, for charts 112time series chart 63

178

time zones 8tool bar 42Topics

See also Domain Topics.access grants and scheduled reports 34as JRXML files 73, 76creating 76defined 76field names in 77JRXML files 73localization 77parametrized queries 59saving Domains as Topics. See Domain Topics.Simple Domain Topic 117uploading 76

Topics and Domains page 67TrueType fonts 88

Uundo 42, 55undo all 42, 56uploading edited design files 150URLs in dashboards 20utilities

iReport 166messages 165

Vvalidating reports 86, 99version attribute in design files 141viewing

dashboards 16fields and data in a Domain 68, 69fields and data in a Domain Topic 74scheduled reports 34

WWidgets Pro 29wizards

Add New Domain 118Choose Ad Hoc Data 67, 76Domain Designer 118Edit Domain Topic 76Report 81

XXML Domain design files 140xmlns attribute in design files 141XSD of Domain design file 140

Documents

Jasper Server 3.7.0 User Guide[1]