TB APplus JasperReports

Technical Description
Jasper Reports
APplus.50.TB.JasperReports.07/2013.002.E
The information and data contained in this document can be changed without any prior notice. No part of this documentation
may be copied or transferred for any purposes – whether electronically or mechanically - without express written consent of
Asseco Solutions AG.
© Copyright 2013 Asseco Solutions AG, Karlsruhe (Germany)
All Rights Reserved.
Content
JasperSoft Products 9
JasperSoft Capabilities...................................................................................................... 9
JasperReports.................................................................................................................10
iReport – Graphical Report Designer..................................................................................11
JasperServer – Interactive Reporting Server.......................................................................12
Comparison between Open Source and Professional Eition ...................................................13
JasperReports Architecture 15
Servers..........................................................................................................................15
APplus Specific Components and Extensions .......................................................................16
Deployment of APplus Specific Components .......................................................................17
Run Time and Design Time View .......................................................................................18
Run Time ..............................................................................................................18
Design Time ..........................................................................................................22
Jasper Report Life Cycle...................................................................................................24
Jasper Report Integration 25

Statistical Reports ...........................................................................................................25
Report Name .........................................................................................................26
Report Design........................................................................................................26
SelParts.xml ..........................................................................................................27
Sel.aspx Implementation Notes................................................................................29
How to … ..............................................................................................................31
Other Reports (Documents, Lists, Out) ..............................................................................35
Report Name .........................................................................................................35
Report Designs ......................................................................................................35
DocTypes.xml ........................................................................................................35
How to .................................................................................................................36
Jasper Reports Production 41

Deployment ...................................................................................................................41
Integration.....................................................................................................................41
JasperServer .........................................................................................................41
iReport .................................................................................................................43
Configuration Files ..........................................................................................................44
JasperServer .........................................................................................................44
iReport .................................................................................................................45
Settings of the Systemconfiguration ..................................................................................46
Technical Description JasperReports Content • 3

iReport AP Extension Plugin 49

Introduction ...................................................................................................................49
Setup and Configuration ..................................................................................................49
Modules .........................................................................................................................52
Report Run (APReportRunExtension) ........................................................................52
Report Localizer (APReportLocalizerPlugin) ................................................................53
Authoring 55
Document Bands (Sections) .............................................................................................55
Fonts.............................................................................................................................57
Styles............................................................................................................................57
Scriptlets and Utility Classes.............................................................................................58
Subreports .....................................................................................................................58
APplus Requirements of Subreport ...........................................................................59
Compiling Subreports .............................................................................................61
Tables ...........................................................................................................................61
Using Bands For Modeling Tables..............................................................................62
Using Frames as a Row Element...............................................................................63
Conditional Displaying or Hiding Columns ..................................................................63
APQE - Query Executer and Query Language ......................................................................64
Report Parameters ..........................................................................................................64
$P!{paramName} Syntax........................................................................................65
APplus Internal or Reserved Parameters....................................................................66
Custom or User Parameters .....................................................................................72
Organization Of the Repository .........................................................................................73
Difference between iReport and JasperServer repository .............................................75
Naming Convention .........................................................................................................76
Naming Convention of Reports.................................................................................76
Documents, Lists, Out.............................................................................................76
Statistical Analysis .................................................................................................76
Examples ..............................................................................................................77
Report Types..................................................................................................................77
Standard Report Templates ..............................................................................................78
Jasper Report Internationalization 79

Internationalization and Localization..................................................................................79
Providing the Locale Information.......................................................................................80
Making Locale Dependent Fields Adaptable to Locale Options (Culture Sensitive Formatting) ....80
Making Static Texts Adaptable to Locale Options .................................................................81
Custom Localization Support....................................................................................82
Additional Information .....................................................................................................84
Jasper Report Internalization Q&A 85

How Can I Localize a Report? ...........................................................................................85
How to Perform Culture-sensitive Formatting? ....................................................................86
APplus Standard Formatting ....................................................................................88
Custom Formatting.................................................................................................89
4 • Content Technical Description JasperReports

How Is the Localization of a Report Set … ..........................................................................91

… in APplus ...........................................................................................................91
… in iReport...........................................................................................................93
… in JasperServer...................................................................................................94
How to Create or Update a Default Resource Bundle? ..........................................................95
How to Create or Update or Translate the Resource Bundle for a New Language?....................95
How Do We Localize Texts in Reports?...............................................................................96
How To Deploy a Report and Resource Bundle(s)? ..............................................................96
How to Select the Report Language on the JasperServer? ....................................................98
How to Select a Language for Printed Documents? ............................................................100
How to Select a Language for Previewed Documents?........................................................102
Styles 103
Creating a New Style .....................................................................................................103
Conditional Styles .........................................................................................................104
Reusing Styles..............................................................................................................105
The Styles Library ................................................................................................105
The Style Template ..............................................................................................106
APplusStyles Template..........................................................................................110
Limitations and Deficiencies...................................................................................110
Not Founded Style from Global Style Template ........................................................111
Jasper Reports Working with Fonts 113

Font Properties .............................................................................................................113
Using Custom Fonts (TTF) in PDF Documents ...................................................................114
Creating PDF Document(s) Containing Unicode Text ..........................................................115
Text formatting.............................................................................................................117
Markup Attributes ................................................................................................118
Is Styled Text Attribute (Deprecated) .....................................................................120
Limitations and Issues ...................................................................................................121
PDF Export Issue..................................................................................................121
PDF Export of Styled Text Doesn't Work When Using Web Service ..............................121
Markup <LI> issue ...............................................................................................122
APplus Print Service 123

Overview .....................................................................................................................123
Setup and Configuration ................................................................................................124
Mandatory Configuration Settings...........................................................................125
Start the Print Server ...........................................................................................127
Technical Description.....................................................................................................128
Notes ..........................................................................................................................129
Jasper Reports Conditional Column Hiding 131

Altering Report Templates at Runtime .............................................................................131
APCustomJSReportService.....................................................................................131
Report Template Requirements ..............................................................................133
Limitations ..........................................................................................................133
Example..............................................................................................................133

Using Special Report Design ...........................................................................................135
AP Query Executer (APQE) 137

AP SQL Query Executer.........................................................................................139
Sel Info Query Executer ........................................................................................141
Mandant Query Executer .......................................................................................143
Web Service Query Executer..................................................................................144
Other APQE components .......................................................................................145
Configuration and Other Files Used by apqe .....................................................................146
applus.config.xml .................................................................................................146
How To ... ....................................................................................................................148
... Activate apqe Logging.......................................................................................148
... Debug apqe.....................................................................................................149
... Jahresvergleich ................................................................................................150
... (Manually) Register apqe ..................................................................................153
Custom PDF exporter 155

Overview .....................................................................................................................155
JasperServer Solution....................................................................................................155
iReport Solution............................................................................................................157
Limitations ...................................................................................................................158
Security 159
APplus Access Rights .....................................................................................................159
Report Permission Configuration ............................................................................160
JasperServer Access Rights ............................................................................................161
Features .............................................................................................................161
Setup and Configuration........................................................................................162
How It Works.......................................................................................................163
Jasper Report Permission Setup 165

Introduction .................................................................................................................165
Set Up the Permissions ..................................................................................................165
Ad Hoc Reporting 167

About … .......................................................................................................................167
… Ad Hoc Reporting ..............................................................................................167
… Topics and Domains ..........................................................................................168
Working With Ad Hoc Reports .........................................................................................169
Notes ..........................................................................................................................170
Limitations ...................................................................................................................171
Quick How To ...............................................................................................................171
Jasper Reports How To 173

How to Use Alias in SQL JOIN Sentence?..........................................................................173
How to Create a Search Criteria with a Field That Is Not Part of the Table? ..........................174
How To Customize Search Criteria (On Sel Pages)? ...........................................................178
How to Ursprungsland optimization, WS utility class report usage example ..........................180

How to add new web service class...................................................................................180

How to measure (WS utility class) performance ................................................................180
How to Hide/Display Rows Conditionally...........................................................................180
How to Hide/Display Column Conditionally .......................................................................181
How to Use Bands for Table Modeling?.............................................................................181
How to Activate apqe Logging? .......................................................................................181
How to Debug apqe? .....................................................................................................181
How to Use Jahresvergleich? ..........................................................................................181
How to Perform Culture-sensitive Formatting? ..................................................................181
How to Set Report Locale? .............................................................................................181
How to Create Default Resource Bundle? .........................................................................182
How to Create/Update/Translate Resource Bundle for a New Language? ..............................182
How Do We Localize Texts in Reports?.............................................................................182
How to Deploy a Report and Resource Bundle(s)? .............................................................182
How to Select a Report Language on the JasperServer? .....................................................182
How to Select a Language for Printed Documents? ............................................................182
How to Select a Language for Previewed Documents?........................................................182
How to Select a Statistical Report Name?.........................................................................182
How to Enable Print/Preview for Statistical Analysis? .........................................................183
How to Determine Needed Entries in SelParts.xml? ...........................................................183
How to Change/Add the Report Format (e.g. HTML)?.........................................................183
How to Pass Custom Parameters to Statistical Reports? .....................................................183
How to Mapping an Old JobTask (WORD, RS, IE) to a JasperReports JobTask?......................183
How to Create a Serial Print Job? ....................................................................................183
How to Customize the Print/Preview Flow? .......................................................................183
How to Pass Custom Parameters to Doc, List, Out Reports?................................................183
How to Configure Report Run Permission?........................................................................184
Display a Value as Duration............................................................................................184
How to Use isnull() in a WHERE Parameter / in the Search Criteria on Sel.aspx? ...................184
How to Solve the Issues of the Field Reader in iReport? .....................................................187
Index 189


JasperSoft Products
Overview The JasperSoft Business Intelligence Suite is a comprehensive Business

Intelligence (BI) suite that provides robust reporting, report server,
data analysis, and data integration. It is available in two editions: Open
Source and Professional. This topic introduces the capabilities and
components of the suite.
Figure 1-1 Overview Of the JasperSoft Business Intelligence Suite
JasperSoft Capabilities
The JasperSoft Business Intelligence Suite brings sophisticated

reporting, interactive analysis and shared services, such as security,
repository and scheduling.
Fundamentals • Seamless embeddability using public Java APIs and Web services
• Extensibility through open source
• External authentication
• Role-based authorization
• Security
• Single Sign-On
• Internationalization
• Configurable and replaceable user interfaces
Technical Description JasperReports JasperSoft Products • 9

Operational Reporting • Graphical report design tool
• Pixel-perfect output to printer, PDF, HTML, XLS, CSV, RTF, TXT, and
XML file formats
• Subreport inclusion for complex reports and dashboards
• Multiple data sources within a single report
• Custom calculations and variables
• Unlimited report size / report virtualization
Managed Reporting • Interactive, parameterized report generation

and Analysis
• Shared repository
• Scheduling
• Automated report distribution
• Compliance snapshots
• Managed ad-hoc data access
Interactive Analysis / • Data exploration: Drill-down, roll-up, "slice-and-dice", pivot, filter

OLAP
• Data visualization: multidimensional tables and charts
• Links to detailed reports and other online resources
• Standard XML/A data access protocol and MDX query language
JasperReports
About JasperReports JasperReports is a Java reporting library. The JasperReports library is

the engine that processes and displays data in comprehensible, pixel-
perfect printouts and Web reports. JasperReports is useful for all types
of applications, ranging from routine invoice printing to sophisticated
executive dashboards.
Quick Facts • Is a Java reporting library.
• Is the reporting engine embedded in the JasperSoft Business

Intelligence Suite.
• Open Source edition can be downloaded from
http://www.jasperforge.org
• Fully supported Professional and Developer Editions available.
10 • JasperSoft Products Technical Description JasperReports

iReport – Graphical Report Designer
About iReport iReport is a graphical report designer for JasperReports and

JasperServer. iReport simplifies the process of accessing data sources,
defining and designing the report layout and compiling reports. iReport
is typically used by report developers to design reports that others
access through the JasperServer or through other business applications.
Power users and developers can also create their own reports using
iReport.
Quick Facts iReport
• is used by report developers and power users.
• exposes and makes it easier to use the JasperReports library.
• integrates with the JasperServer to allow report developers to

centrally manage JasperReports resources.
• Open Source edition (iReport) can be downloaded from
• available in Professional and Developer Editions with JasperReports.
Figure 1-2 iReport

JasperServer – Interactive Reporting Server
JasperServer is a stand-alone and embeds ad hoc and interactive

reporting server, enabling delivery of mission critical information on a
real-time or schedule basis to the Web, to the printer, or to a variety of
file formats.
Through its support for easy to use self-service Web 2.0 interactive
reporting, JasperServer enables users to meet their own reporting
needs, without burdening IT or software application developers.
JasperServer also provides a common framework infrastructure on top
of which reporting, data analysis, and data integration products can be
made available.
JasperServer provides the following shared services:
• Security services: Built-in authentication, or single sign-on

integration with external authentication systems such as LDAP.
• Repository services: Robust and scalable secure object storage for a

broad range of content types.
• User interfaces: All out-of-the-box user interfaces applications can

be easily customized or replaced using the underlying public
integration interfaces.
• Scheduling services: Built-in scheduling service provides for offline

execution of large or periodic tasks such as standard reports.
Figure 1-3 JasperServer

Quick Facts • Provides intuitive web-based ad hoc reporting for business users.
• Provides a friendly Web interface for business users to access and

interact with reports and analyses.
• Is an interactive report server.
• Can schedule, run, and distribute reports to users and groups.
• Secures reports and analyses based on users and roles.
• Manages shared resources, such as report definitions, images, data

source definitions, and so on.
• Provides historical report versioning and auditing for regulatory

compliance.
• Can be embedded in (used by) other Web applications.
• Open Source edition can be downloaded from.
• Available in Professional Edition.
Comparison between Open Source and Professional Eition
Open Source Professional Edition
Operating Systems Linux and Microsoft Windows IBM AIX, Sun Solaris, Red Hat
Enterprise Linux (RHEL), Novell
SUSE Linux, Fedora Enterprise
Linux, Mac OS X, Debian Linux,
HP-UX, rPath Linux, Microsoft
Windows
Web/application servers JBoss or Apache Tomcat JBoss, Apache Tomcat, IBM

WebSphere, BEA WebLogic,
Oracle Application Server (OAS),
Sun Glassfish
Databases MySQL MySQL, Oracle, IBM DB2,

Microsoft SQL Server,
PostgreSQL, EnterpriseDB,
Ingres
Directory provider Hibernate Hibernate, LDAP, IBM Tivoli,

Microsoft Active Directory


JasperReports Architecture
Servers
JasperServer is tightly integrated in APplus. It services requests from

the web server (as well as from the print server) and requests
information from application server and database server.
Figure 2-1 APplus Integration Of the JasperServer
Where
• the JasperServer is responsible for report rendering and

management (storing, editing (ad-hoc)).
• the web server is responsible for interaction with the users and the
data presentation.
• the application server provides the business logic.
• the database server stores the data.
The JasperServer is a java based web application running on Tomcat

web server. It uses a MySql database server for the server repository.
(For more information about the features of the JasperServer see
section "JasperServer – Interactive Reporting Server" on p. 12)
Technical Description JasperReports JasperReports Architecture • 15

Note The JasperServer is able to use different application servers and is able
to use different database servers to host its repository.
• Supported application servers are: Tomcat, JBoss, GlassFish,

WebSphere, WebLogic.
• Supported database servers are: MySql, Microsoft SQL Server,

Oracle, DB2, PostgreSQL.
More Details are available in the Documentation "JasperServer Pro

Install Guide"
<JasperServer>\docs\JasperServer-Pro-Install-Guide.pdf
APplus Specific Components and Extensions
Jasper Extensions APJasperExtensions is a bundle of APplus extensions for

(APJasperExtensions) JasperReporting. It is deployed to JasperServer and iReport. The bundle
includes:
• APCustomJSReportService, provides the functionality of column

removing and fixes the PDF export of HTML text.
• APplusAuthFilter, provides the user authentication and authorization

functionality. Identification (not Authentication) is performed via
NTLM. Authorization is done via the APplus Security Manager.
• APQueryExecuter, is the extended SQL query executer. It supports

APplus specific SQL syntax and keywords.
iReport Plugin
(APReportExtensions- APReportExtensionsPlugin is a bundle of APplus plugins for iReport. It is
Plugin) deployed to iReport. The bundle includes:
• APReportRunExtension is a iReport plugin that provides AP specific

report execution. The plugin uses functionality provided by the
APCustomJSReportService.
• APReportLocalizerPlugin is a iReport plugin that allows report

localization from iReport. It uses APReportLocalizer utility that
substitutes static texts in reports with resource bundle keys and
creates or updates a resource bundle.
16 • JasperReports Architecture Technical Description JasperReports

Report Scriptlets
(APReportsScriptlets) Jasper Report Scriptlets
A scriptlet is a Java class used to execute special elaborations during

print generation. The scriptlet exposes a set of methods that are
invoked by the reporting engine when some particular events occur, like
the creation of a new page or the end of processing a detail row. To
implement a scriptlet, we have to extend the Java class
net.sf.jasperreports.engine.JRAbstractScriptlet
This class exposes all abstract methods to handle the events that occur
during report generation and provides data structures to access all
variables, fields, and parameters present in the report.
APReportsScriptlets
APReportsScriptlets is a jar file that bundles java classes that are used
during report rendering. There are two types of classes:
• The ones that implement the scriptlet interface (scriptlets) and
• the ones that consume web services (utility classes).
For detailed information about scriptlets and utility classes see

Schulungshandbuch APplus Jasper Reports and Chapter "Anhang 3:
Scriptlets und Utility Klassen".
Print Server APplusPrintService is a stand alone application/service used for

(APplusPrintService) report/document printing. It can run as an application or as a service.
Deployment of APplus Specific Components
Figure 2-2 Overview Of the APplus Extension Of the Jasper Components
There
• are components deployed to the JasperServer.
• are components deployed to iReport.
• is a print Server deployment.

Run Time and Design Time View
Run Time
The JasperServer is used to store and render reports. The jasper

rendering engine is part of the JasperServer. Reports are stored in
database based repository on the JasperServer.
Preview Operation
Figure 2-3 Preview Operations
Server Interaction
1. Report rendering is requested (the web service who uses the

runReport() method)
2., 3. JasperServer reads the report from the repository.
4., 5. The database connection parameters are obtained from the application
server. The application server expands the SQL query from the report
to a fully qualified SQL query.
6., 7. A connection to the SQL server is created and the SQL query is
executed on the database server
8. The rendered report is returned to the web server.
9. The rendered report is forwarded to the web client.

Operation Flow
Figure 2-4 Preview Operations As an UML-diagram
1. The user selects on a APplus page to preview a report.
2. The user selection and the internal parameters are collected.
3. The report rendering request is generated. The runReport()method of

the web service is used to start the report rendering on the
JasperServer.
4. The JasperServer gets the report from the repository and selects the
appropriate query executer based on the query language used in the
report.
5. APplus uses a proprietary query language - apqe. In this case the

APQueryExecuter is selected. The APQueryExecuter
• obtains the database connection parameters from the application

server.
• creates the connection to database server.
• preprocesses the SQL query and sends it then to the application

server. The application server expands the query to a fully qualified
SQL query.
• executes the fully qualified SQL query on the database server and
returns the result to the rendering engine.
6. The JasperServer renders and exports the report.
7. The rendered report is returned as a result to the runReport() request
8. The web server forwards the result to the web client.

Print Operation
Figure 2-5 Print operations
Server Interaction
1. The user selects on a APplus page to print a document.
2. On the web server the print request is created and added to the job
queue.
3. The print server checks the table JOB for print jobs.
1. The print server gets the print job from the table JOB.
2. The print server processes the job and creates a report rendering
request on the JasperServer (web service, runReport() method)
3., 4. The JasperServer reads the report from the repository.
server. The application server expands the SQL query from the report
to a fully qualified SQL query
7., 8. The connection to the SQL server is created, the SQL query is executed
on the database server.
9. The rendered report is returned to the print server in the .jrprint format
10. The print server prints the report to the printer.
11. The print server exports the report (to PDF) and stores it to the
document management system (DMS).

Operation Flow
Figure 2-6 Print Operations As an UML-diagram
1. The user selects on a APplus the print dialog to print a report.
2. The selection of the user and the internal parameters are collected.
3. The print request is created and added to the tableJOB.
4. The print server checks the table JOB periodically.
5. The print server gets the print job from the table JOB.
6. The print server processes the job and creates the report rendering
request on the JasperServer (web service, runReport() method).
7. The JasperServer gets the report from the repository and selects the
appropriate query executer based on the query language used in the
report.
8. APplus uses the proprietary query language - apqe. In this case the
APQueryExecuter is selected. APQueryExecuter

server.
• creates a connection to the database server

server. The Application server expands the query to a fully qualified
SQL query.
returns result to the rendering engine.
9. The JasperServer renders the report to the intermediate format,

.jrprint.
10. The rendered report is returned as a result of the runReport() request

(in .jrprint format)
11. The print server prints the report to the printer.
12. The print server exports the report (to PDF) and stores it to the
document management system (DMS).

Design Time
The JasperServer is not used to store and render reports. The jasper
rendering engine is part of iReport. The reports are stored in the
repository on the local file system.
iReport - Server Interaction
Figure 2-7 iReport - Server Interaction
1., 2. The report is selected and opened from the local file system.
server, the application server expands the SQL query from the report to
the fully qualified SQL query.
5., 6. The connection to the SQL server is created. The SQL query is executed
on the database server.

iReport - Run Report Flow
Figure 2-8 iReport - Run Report Flow
1. The report is selected from the local file system and opened in iReport.
2. The user selects to execute (run) the report.
3. iReport prompts the user to enter the parameters.
4. iReport uses the jasper rendering engine to render the report.
5. The Jasper rendering engine selects the appropriate query executer

based on the query language used in the report.
6. APplus uses a proprietary query language - apqe. The APQueryExecuter

is selected. The APQueryExecuter

server.
• creates the connection to the database server.

server. The application server expands the query to a fully qualified
SQL query.
returns the result to the rendering engine.
7. The Jasper rendering engine renders the report to the intermediate

format .jrprint.
8. Depending on the user selection in iReport for the report format, the
report is exported to the selected format (PDF, RTF, XLS, HTML, etc.).

Jasper Report Life Cycle
It is possible to define two distinct action groups:
1. actions that have to be executed during the development phase (design

and planning of the report, and compilation of a JASPER file source) and
2. actions that have to be executed in a run time system (loading of the

file and production of the print).
Figure 2-9 Jasper Report Life Cycle
The Report Life Cycle
• A report is described by a source file, in XML format. The official

extension of these source files has become .jrxml (i.e.,
JasperReports XML). It can be hand-coded, generated, or designed
using a tool. The file format is defined by a Document Type
Definition (DTD).
• These source files are compiled to create a JASPER file (with the
.jasper extension), which is a kind of predefined report. The main
difference between using XML and a .jasper file is that the XML file
should be compiled at runtime using the JasperCompileManager
class.
• The JASPER file is loaded in a runtime system and is joined to

records coming from a datasource in order to create a print
(.jrprint).
• .jrprint is a universal format that can be exported in the desired

format (e.g., PDF or XLS).

Jasper Report Integration
In general integrating a report isn't particulary difficult. All we have to

do is modifying a XML file and the report appears in the print/preview
pop-up menu in APplus. When data needs to be preprocessed on the
web server or when we want to pass customer parameters to the Jasper
reporting server, then the integration becomes more complex.
The integration of statistic reports differs from the integration of other

reports (documents, lists, out). Both are presented bellow.
Statistical Reports
When we create or modify a report for statistical analysis, we need to

collect the following information:
• Will the statistic provide multiple analysis types?
• Will the statistic provide different groupings?
The answers (to the above questions) will
• influence the report name
• influence the report design
• define the entries in the SelParts.xml file.
Technical Description JasperReports Jasper Report Integration • 25

Report Name
Naming Convention The Report name for statistical report is generated. We need to follow
the same rules (naming convention) as in the code when we name a
master report. The name is based on
• the table name and
• the analysis type.
The name generation process
• obtains the table name from the name of the page used for
statistical analysis.
• It is assumed that the Sel-page is named after the (base) table

that is used for statistic analysis. The table name is "extracted"
from the name of the Sel-page by removing the Sel.aspx string.
• obtains the analysis of the user selected from the Sel-page.
• joins the table name and analysis type:
• the table name is written in lower cases,
• the analysis type starts with a capital letter,
• if analysis type is not defined, then the report name contains

only the table name.
Examples • auftragKurz
• abcAnalyseAV
• lagerbelegung
Report Design
For each analysis type is separatly a report to be created. For different

groupings (of the same analysis type) one report is created!
Different groupings in a single report sometimes require modification of

the SQL query. Jasper reporting allows modifying the report query at
run-time. We provide the grouping specific snippets from the web ser-
ver. The snippets have to be stored in the file SelParts.xml that is
stored in the directory webobjects on the web server.
26 • Jasper Report Integration Technical Description JasperReports

SelParts.xml
The file SelParts.xml is an XML file stored in the webobjects directory on

the web server. It contains the SQL snippets that are needed to
generate the full SQL query for specific groupings. The file is also used
to integrate the Jasper statistic reports in APplus. The Jasper statistic
reports can be printed/previewed from pages for statistical analysis,
when the statistic table name is defined in the file SelParts.xml.
<table name="table_name">
<analysis [name="analysis_type"]>
<group [name="grouping"] />
[<fields> </fields>]
[<join><join>]
</group>
</analysis>
</table>
• table, analysis and group are mandatory nodes. The name attribute
is mandatory only for the table node.
• table can contain [0..n] analysis. We use the name attribute,

when the multiple analysis types needs to be defined. The name
must be same as defined on the Sel.aspx page.
• analysis can contain [0..n] groupings. We use the name

attribute when multiple groupings needs to be defined. The
name must be the same as defined on the Sel.aspx page.
• fields and join nodes are optional. We define them when the
grouping require modifications of the SQL query.
• Group can contain [0..1] fields nodes.
• Group can contain [0..1] join nodes.
comment example
statistic page with: <table name="inventurhist">

NO analysis type, <analysis>
NO grouping <group />
</analysis>
</table">
statistic page with: <table name="bewertung">

analysis type uebersicht, <analysis name="uebersicht">
NO grouping <group />
</analysis>
</table">

comment example
statistic page with: <table name="lagerumbuchungsliste">

NO analysis type, <analysis>
grouping umbuchung <group name="umbuchung">
<join />
<fields>
,GRUPPE=t.ABGANGSLAGER, GRUPPENNAME=''
</fields>
</group>
</analysis>
</table">
statistic page with: <table name="bmk">

multiple analysis types, <analysis name="lang">
multiple groupings <group name="artikel">
<join>
</join>
<fields>
,GRUPPE=bmk.artikel, GRUPPENNAME=ARTIKEL.NAME, GRUPPE2=
</fields>
</group>
<group name="bmk">
<join>
</join>
<fields>
,GRUPPE=bmk.bmk, GRUPPENNAME=, GRUPPE2=
</fields>
</group>
</analysis>
<analysis name="nobestand">
<group name="artikel">
<join>
</join>
<fields>

comment example
</fields>
</group>
</analysis>
<analysis name="bewegung">
<join>
</join>
<fields>
</fields>
</group>
<group name="bmk">
<join>
</join>
<fields>
,GRUPPE=T3.SERIENNR, GRUPPENNAME=, GRUPPE2=''
</fields>
</group>
</analysis>
</table">
Sel.aspx Implementation Notes
Sel.aspx pages usually contain _auswertung and selobj variables. The

variable _auswertung is used to store analysis type whereas selobj
stores grouping. There is one exception, though. When the analysis
type is not defined, the variable _auswertung contains grouping. The
functionality was not changed with the integration of Jasper Report in
APplus in order to maintain support for legacy HTML statistics reports.
The Jasper integration in APplus solves this inconsistency by defining
the variable selobj in addition to the variable _auswertung in such
cases. The selobj contains grouping information as well.
When we integrate Jasper reports to an existing Sel.aspx page,
• that doesn’t provide analysis type selection,
• but allows to group data differently,
we have to
• leave _auswertung as it is (i.e. assigned to grouping)
• pass grouping information in selobj as well

• modify the controlAndNav()-function as described below:

function controlAndNav(format)
{
// immer durchgeführter Code:
// hier keinwe Ueberpruefung notwendig
if (format) {
if (window.event.altKey) {
openList(_auswertung.value);
} else {
selobj = _auswertung; <-----add this line
openReport(format);
} // if
} // if
} // controlAndNav
Analysis Type / The _auswertung and selobj values for other cases are presented in
Grouping Matrix Analysis type/Grouping matrix.
analysis type
Yes No
multiple Yes _auswertung = analysis type, _auswertung = grouping,
groupings
selobj = grouping selobj = grouping
No _auswertung = analysis type, _auswertung = ,
selobj = not defined selobj = not defined
When we create a Sel.aspx page (from the scratch)
• that doesn’t provide analysis type selection,
• but allows to group data differently,
we have to:
• leave _auswertung without a value and

• pass grouping information in selobj
Analysis Type / The _auswertung and selobj values for other cases are presented in
Grouping Matrix Analysis type/Grouping matrix.
analysis type
Yes No
multiple Yes _auswertung = analysis type, _auswertung =,
grouping
selobj = grouping selobj = grouping
No _auswertung = analysis type, _auswertung =,
selobj = not defined selobj = not defined

How to …
… Select Statistical Report Name?
Notes The report name for the (master) statistic report is generated. The
name is predefined!
The table name must be written in lowercases, the analysis type must
start with a capital letter.
The report name format is:
• master report: table[Analysis].jrxml
• subreport: table[Analysis][subreport_name]_sub.jrxml
Report Name
Selection Process
1. Get the table name from the name of the Sel.aspx page, i.e.
nameSel.aspx -> name.
2. Get the name of the analysis type,
• if multiple analysis types are defined (on the Sel.aspx page)
• determine the value of _auswertung variable (e.g. Auswahl als

URL, check the value of _auswertung in the URL)
• combine Sel-page name and _auswertung
Example: angebotSel.aspx, Auswertungsart: Kurzübersicht

(_auswertung=KURZ) -> angebotKurz.jrxml
• if no analysis type is defined
• only the Sel.aspx page name is used
Example: wauftragposSel.aspx -> wauftragpos.jrxml

… Enable Print/Preview for Reports for Statistical Analysis?
1. Create a (default) entry in the SelParts.xml file.
• The name attribute of the table node must be the name of the
Sel.aspx page.
• this will enable the print and preview menu
<table name="table">
<analysis>
<group />
</analysis>
</table>
2. For each supported analysis type create a new <analysis name="">

node, e.g.
<table name="abcanalyse">
<analysis name="vt">
<group />
</analysis>
<analysis name="vt2">
<group />
</analysis>
3. For each grouping provided (for analysis type) create a new <group
name=""> node, e.g.
<table name="zplan">
<analysis>
<group name="abrechngruppe" />
<group name="abteilung" />
<group name="kost" />
<group name="keine" />
</analysis>
</table>
4. For each group create <fields> and <join> nodes as appropriate, e.g.
<table name="angebot">
<analysis name="kurz">
<join>left outer join artikel gj ON t.artikel =
gj.artikel</join>
<fields>,MONAT = 0, GRUPPE = t.ARTIKEL, GRUPPENAME =
gj.name</fields>
</group>

… Determine Needed Entries In the SelParts.xml File?
The table, analysis and group nodes in SelParts.xml have a name

attribute.
• The values of the name attribute are obtained from the Sel.aspx
page.
• We can get them from the URL (if we press the Auswahl als URL
button).
• table name = obtained from the name of the aspx-page, i.e.

bestellungsel.aspx -> bestellung.
• analysis name = _auswertung (i.e. KURZ)
• group name = _gr_kurz (i.e. Artikel)
Figure 3-1 Determine Needed Entries In the SelParts.xml File
… Change / Add a Report Format (e.g. HTML)?
The report format of statistical analysis is predefined. It can be PDF or

Excel.
To change or add a format it is necessary to modify the code in

selUtils.js, openReport()
if ( isPreview ) {
jobTyp = popUpMenu("Reporting Services, Jasper Server (PDF), Jasper Server (Excel)");
<-- add/modify menu
} else {
jobTyp = popUpMenu("Reporting Services, Jasper Server (PDF)");
}
if (( 2 == jobTyp ) || ( 3 == jobTyp )) { <-- update selected format
openJasperReportingReport(jobTyp == 2 ? "PDF" : "XLS"); <-- handling appropriately
}

... Pass Custom Parameters to Report?
Reports of statistical analysis use Sel.aspx pages to create a selection

filter.
The elements (fields, checkboxes, etc.) on Sel.aspx pages are basically

divided in two categories:
• one that have names equal to DB field names and
• one that are not named as DB field names.
When the report is previewed or printed:
• the user input of the statistic analysis is collected,
• a collection of key=value pairs is constructed (selectedFields(),

selUtils.js),
• the collections are assigned to the WHERE report parameter,
• selected elements with names ending with "_" are added to URL as
distinct report parameters (getExtendedReportParam(), selUtils.js),
• all parameters that are part of the URL are passed to the report.
To pass user selection (parameter) from the Sel.aspx page to the

report:
• use elements that have names ending with "_".
The selection is passed to the report as a report parameter with the

same name, e.g. an element of the Sel.aspx page named ende_ will be
a parameter named ende_ in the report.

Other Reports (Documents, Lists, Out)
Report Name
Report names are freely definable. They have to follow the naming con-
vention, though. The report name is defined in the DocTypes.xml file.
Report Designs
Three types of report designs exist:
• document – business documents, e.g. invoice, order, etc.,
• list – master data list, e.g. company list, person list, etc. and
• out – free form report.
Each design has a Type. A type has to be defined in the DocTypes.xml

file. Each report type has some specific in print/preview flow. The
specifics can be seen in the
WebObjects\jobUtils.js, selectPrint()
function.
DocTypes.xml
The DocTypes.xml file is used to register the report and to define a

print job. The file is located in the directory WebObjects on the web
server. In this section we will cover only the nodes in the DocTypes.xml
file that are applied to jasper reporting.
Figure 3-2 Nodes In the DocTypes.xml

Tag Description
<jobASP> P2plusJS.aspx - the page used to create Jasper report rendering

request
<jobTask> JRBELEG - document report type, i.e. business documents

JRLIST - list report type, i.e. master data lists
JR - free form report type, i.e. out pages
<jobDotFile> Contains the report name (without the .jrxml extension).

The optional parameter @language is used to define the supported
languages. For each language a separate node has to be created, but
the report name is identical.
<module> With this node it is possible to overwrite the default determination of

the path, which contains the information about the module from the
URL of the page, which invoke the report.
The usage of the node is optional. But if the node is specified, then is
the value of the attribute is name of the directory, which contains
the report.
<jobFormat> PDF or RTF - report format. It could be any of Jasper supported

formats.
<jobUserParam> Used to define the user parameters that are passed from APplus to
JasperServer. The @name attribute defines the parameter name.
The parameter value is nodes inner text.
How to ...
... Mapping an Old Job-Task (WORD, RS, IE) to JasperReports

Job-Task
When converting an existing report (designed as Word template, MS

Reporting report or HTML page) consider the following table when you
define the jobTask node in the DocTypes.xml file.
report type previous jobTask JasperReports

jobTask
document RSBELEG, WORD, IS JRBELEG
list RSLISTS JRLIST
out page RS, IEPR JR

... Create a Serial Print Job?
There exist two possibilities to create serial print jobs.
Standard Serial Serial printing for a document is configured in the DocTypes.xml file.
Printing Usually nothing else needs to be done.
• To enable serial printing we have to set the massJob attribute in the

jobType node as follows: massJob="true", e. g.
<jobType id="Packliste (JR PDF)" title="Packliste (PDF)"

PrintDialog="true" massJob="true">
• Standard serial printing is implemented by
WebObjects\jobUtils.js, printSerieStep()
Customized Serial Printing
Customized serial printing can be configured in the DocTypes.xml file.

We have to set the attributes in the jobType node as follows:
external="true"
massJob="false"
Example:
<jobType id="lsexternserie (JR PDF)" PrintDialog="false"
title="Serie Lieferschein (PDF)" external="true"
massJob="false">
The customizations are usually implemented in several places:
• externalPrint() function in the Rec.aspx page
• web service function(s)
The Example Warenausgang, Lieferschein serial printing is implemented

as follows:
• It starts with the externalPrint() function in the Rec.aspx page,

where the SOAP job is created in the job table
• The job invokes the warenausgang web service

(preMassPrintJobs(), on the web server), where preprocessing is
performed.
• The preMassPrintJobs() invokes the web service

(preMassPrintJobs()) on the application server, where the final
processing is done.
• If processing succeeds, the print job is created in the job table (on
the application server).
The documents are finally printed by Print server.

... Customize Print/Preview Flow?
When we need for example to obtain some additional information from

Rec.aspx page or perform additional processing to customize
print/preview:
1. Use the externalPrint() function
• the function has to be implemented by the Rec.aspx page.
• the function has to invoke
• startJob() for print operation or
• startReport() for preview operation
• in the DocTypes.xml define the jobType node and set the external
attribute set to true.
Figure 3-3 Definition of the jobType node
Example: Lieferschein (JR PDF) check the following files:
• WarenausgangRec.aspx
• DocTypes.xml, jobType id="Lieferschein (JR PDF)"
• jobUtils.js, selectPrint(), startReport()

... Pass Custom Parameters to a Report?
Report parameters can be defined by the user. They can be used
• to pass information from the web server to the report (rendered by

JasperServer).
• to influence the report rendering.
• to be displayed in the report.
To pass custom parameters to report, we can
• use the externalPrint() function to collect user information and pass

it to the report server (example doesn't exist).
• define a parameter in the DocTypes.xml file (example provided in

DocTypes.xml)
Example: Auftrag report without total sum.
The user has a possibility to select to print a report with or without total
sum.
• The report Auftrag with total sum is already registered in the
DocTypes.xml file.
• Register the report Auftrag without total sum in the DocTypes.xml

file.
<jobType id="Auftrag_nts" title="Auftrag (w/o total sum)"
PrintDialog="true">
<jobASP>P2plusJS.aspx</jobASP>
<jobTask>JRBELEG</jobTask>
<jobDotFile language="de">auftragAuftrag</jobDotFile>
<jobUserParam name="upPrintTotalSum">no</jobUserParam>
<jobFormat>PDF</jobFormat>
<jobPrinter>
<printPages>1</printPages>
<printer>(default)</printer>
</jobPrinter>
<archivType>Web</archivType>
<archiv>/archive/auftrag/</archiv>
</jobType>
• use the jobUserParam node to define parameter name (e.g.
upPrintTotalSum) and its value (e.g. no)
<jobUserParam name="upPrintTotalSum">no</jobUserParam>
When the user selects Auftrag (w/o total sum) from the print/preview
menu
• the upPrintTotalSum parameter with value no is added to the report

parameters that are sent from APplus to the JasperServer.
• the Auftrag report contains an expression that evaluates the value

of upPrintTotalSum parameter.
• the total sum is not printed when the parameter exists and its value
is no.


Jasper Reports Production
This chapter contains information about various integration files, their

purpose and deployment.
Deployment
For detailed information about the deployment and integration steps for
the production system see Technische Beschreibung Jasper Reports
installieren und administrieren and Chapter "Deployment".
Integration
Note: The Integration has to be performed with the Reporting plugin of

the APplus Manager. With the following command APplus Manager >
Reporting > Jasper Integration you can use the plugin.
In the following section you find the explanation of the steps performed
by the APplus Manager during the integration.
JasperServer
1. Copy JAR files (APJasperExtensions.jar, barcode4j.jar, jtds.jar) - the

mandatory jar files are deployed to the JasperServer to the lib folder
../jasperserver-pro/WEB-INF/lib folder
• APJasperExtensions.jar - bundle of AP extensions, needed for the

integration of Jasper reporting in APplus (see Chapter "APplus
Specific Components and Extensions" on p. 16).
• jtds.jar - open source JDBC driver
• barcode4j.jar - open source barcode generator
2. Copy barcode/Java support from iReport. For the JasperServer-Pro

server the following jar files are not required (iReport.jar,
barbecue*.jar, bsh*.jar)
Technical Description JasperReports Jasper Reports Production • 41

3. Activate the AP Query Executor and export the options (jasperre-

ports.properties) - updates existing Jasper Server files located at
.../jasperserver-pro/WEB-INF/classes
• Registers the apqe query language (see Section "... (Manually)

Register apqe" on p. 153)
• Adds export options for excel files.
4. Activate the APplus extensions (applicationContext.xml) - updates

existing Jasper Server file located at
../jasperserver-pro/WEB-INF
• Registers the apqe query language (see Section "... (Manually)

Register apqe" on p. 153)
• registers the custom PDF exporter - the class
com.apag.p2plus.p2reports.CustomReportService
implementing the custom PDF exporter is registered (see section

"JasperServer Solution" on p. 155)
• registers the conditional colum hide/display extension - the class
com.apag.p2plus.p2reports.CustomReportService
implementing the conditional colum hide/display extension is

registered (see section "JasperServer Solution" on p. 155)
5. Copy selection XML from the APplus web server (sel.xml, SelParts.xml)
• sel.xml - The file is used when statistical reports are executed.
Needed by the APSelinfoQueryExecuter (see section "Sel Info Query

Executer" on p. 141)
• SelParts.xml - The file is used when reports are executed on the

JasperServer (see section "SelParts.xml" on p. 27).
6. Create APplus configuration (applus.config.xml) - creates a

configuration file for apqe. The file is used when reports are executed
on the JasperServer. The file is created in the classes folder
../jasperserver-pro/WEB-INF/classes
(see section "applus.config.xml" on p. 146)
7. Copy the PDF font map and the arial fonts (fontmap.xml (see section
"APplus Specific Components and Extensions" on p. 16), ari*.ttf) -
copies the default font map and fonts to the folder
The map is used when JasperServer exports reports with MARKUP texts
to PDF (see section "Markup Attributes" on p. 118).
8. Activate the APplus authorization filter (applicationContext-

security.xml) - enables the APplus report execution permission checking
(see section "Setup and Configuration" on p. 162)
42 • Jasper Reports Production Technical Description JasperReports

iReport
1. Copy the jar files (APJasperExtensions.jar, barcode4j.jar, jtds.jar) - the

mandatory jar files are deployed to iReport.
The files are deployed to the folder
../iReport/lib
• APJasperExtensions.jar - a bandle of APplus extensions (see section

"APplus Specific Components and Extensions" on p. 16).
• jtds.jar - open source JDBC driver
• barcode4j.jar - open source barcode generator
2. Activate the APplus Query Executor and export the options

(jasperreports.properties) - updates existing iReport file (located at
.../iReport/classes).
• Registers apqe query language (see Section "... (Manually) Register

apqe" on p. 153)
• Adds export options for excel files.
3. Copy the selection XML from the APplus web server (sel.xml,
SelParts.xml):
• sel.xml - The file is used when statistical reports are executed.

Needed by APSelinfoQueryExecuter (see section "Sel Info Query
Executer" on p. 141).
• SelParts.xml - The file is used when statistical reports are executed

in iReport (see section "SelParts.xml" on p. 27).
4. Create the APplus configuration file (applus.config.xml) - Creates a

configuration file for apqe. The file is used when reports are executed in
iReport. The file is created in the folder
../iReport/classes
(see section "applus.config.xml" on p. 146).
5. Install the APplus plugin (APReportExtensionsPlugin.jar) - the APplus

iReport plugins are deployed to iReport. The files are deployed to the
folder.
.../iReport/lib
APReportExtensionsPlugin is a bundle that includes (see chapter

"iReport AP Extension Plugin" on p. 49):
• APReportRunExtension - iReport plugin that provides APplus specific

report execution. The plugin uses functionality provided by
APCustomJSReportService (see section "Report Run
(APReportRunExtension)" on p. 52).
• APReportLocalizerPlugin - iReport plugin that allows report

localization from iReport (see section "Report Run
(APReportRunExtension)" on p. 52).
6. Copy the PDF font map and the arial fonts (fontmap.xml (see section
"APplus Specific Components and Extensions" on p. 16), ari*.ttf) -
copies the default font map and fonts to the folder
../iReport/classes

The map is used when iReport exports reports with MARKUP texts to
PDF (see section "Markup Attributes" on p. 118).
Configuration Files
Note: The configuration files are managed and deployed by the APplus
Manager.
1. Open the APplus Manager.
2. Open the reporting plugin and then the tab Jasper Integration.
Here the configuration files, which are managed and deployed by the
APplus Manager, are listed here as a quick reference and checklist.
JasperServer
File Deployment Purpose Comment

Path
applicationContext.xml ../jasperserver- register apqe (see

pro/WEB-INF Section "... (Manually)
Register apqe" on
p. 153)
register custom PDF
exporter (see section
"JasperServer
Solution" on p. 155)
applicationContext-security.xml ../jasperserver- authentication filter

pro/WEB-INF registration (see
section "Setup and
Configuration" on
p. 162)
log4j.properties .../jasperserver- enable apqe logging

pro/WEB-INF (see section "...
Activate apqe Logging"
on p. 148)
applus.config.xml .../jasperserver- mandatory parameters apqe reads this

pro/WEB- (see section file only when
INF/classes "applus.config.xml" on the report is
p. 146) executed on
the
JasperServer
(web interface)
jasperreports.properties .../jasperserver- • apqe registration

pro/WEB- (see Section "...
INF/classes (Manually)
Register apqe" on
p. 153)
• export option
aktivation
sel_<company_name>.xml .../jasperserver- needed by APSelinfo-

pro/WEB- QueryExecuter
INF/classes

File Deployment Purpose Comment

Path
SelParts_<company_name>.xml .../jasperserver- apqe reads this

pro/WEB- file only when
INF/classes report of
statistical
analysis is
executed on
the
JasperServer
(web interface)
fontmap.xml .../jasperserver- needed by the custom

pro/WEB- PDF exporter (see
INF/classes section "JasperServer
iReport
File deployment path Purpose Comment
log4j.properties .../iReport/classes enable apqe logging

(see section "...
Activate apqe
Logging" on p. 148)
applus.config.xml .../iReport/classes mandatory apqe reads this

parameters (see file only when
section the report is
"applus.config.xml" executed in
on p. 146) iReport
jasperreports.properties .../iReport/classes • apqe registration

• export option
activation (see
section "...
(Manually)
Register apqe"
on p. 153) (see
iReport section)
sel_<company_name> .xml .../iReport/classes needed by APSel-

infoQueryExecuter
SelParts_<company_name> .../iReport/classes apqe reads this

.xml file only when
the report of
statistical
analysis is
executed in
iReport
fontmap.xml .../iReport/classes needed by the

custom PDF exporter
(see section
"JasperServer

Settings of the Systemconfiguration
Group Sub-Group Key Description Comment
Module Module Reporting When this checkbox is set, the by default the
Services Reporting Services entry will be Reporting Services
statistik report available in the statistics menu. statistik report is
Note that Reporting Services enabled
fuer SQL has to be set as well
(Reporting Services module has
to be activated).
With this checkbox we have a
possibility to control the support
for Reporting Services based on
statistical reports independently
from Reporting Services support
for business related reports
(documents). When the Repor-
ting Services module is active,
we can disable the generation of
statistical reports with Reporting
Services (the Reporting Services
entry won’t be displayed in the
menu) by removing the check
from checkbox.
Module Module JasperServer enables/disables the Jasper Re- by default the

reporting for porting module. When the JasperServer
SQL Jasper Reporting module is reporting is
active the print & preview enabled.
menus will contain the Jasper
related entries and the user can
select to generate a report with
Jasper Reporting.
Report- General Setting of Enables user selection when the default value:
ing "Printing" "Gedruckt" flag will be set. The before printing
checkbox possible options are:
• before printing
• after printing

Report- JasperServer JasperServer The path to the JasperServer

ing URL repository web service. You can
call the corresponding web ser-
vice by entering the following
URLs:
• JasperServer Open Source:
http://localhost:8080/jasper
server/services/repository
• JasperServer Professional:
http://localhost:8080/jasper
server-
pro/services/repository
Where:
• localhost - is the name of
the computer on which the
JasperServer is installed and
• 8080 - is the port that was
specified during installation.
Report- JasperServer JasperServer Folder of the JasperServer in-

ing installation stallation (it can also be the net-
path work share)
Report- JasperServer JasperServer Account to access the web ser-

ing user vices (The web services accept
the same accounts as the
JasperServer Web page).
Note: An account that can make
changes to the repository is
required, that is one that can
execute operations (deploy,
change, deleted).
Report- JasperServer JasperServer Password for the account used

ing Password to access the web service
Report- JasperServer Save preview Allows to select document store- Default value:
ing in DMS age behavior during preview. checked
When the checkbox is set, the
documents will be stored to DMS
also during preview.

Report- Print Server The first The first instance of the print The print server
ing instance server defined in the configu- supports several
ration file. instances, each of
which works with
its own web server.
The instances are
specified in a con-
figuration file. Each
instance has a uni-
que name. The
print server instant-
ces can each be set
up for specific en-
vironments or
users. More infor-
mation is available
in the Print Server
documentation (see
"Mandatory
Configuration
Settings" on page
125).
Report- Print Server Users of the Users (separated with ";") who
ing first instance use the print server. All print
jobs that have been created by
these users are processed by
"Instance 1" (the unique name
of the print server instance).
Report- Print Server Environments Environments (separated with

ing for the first ";") that the print server uses.
instance All print jobs that have been
created in these environments
are also processed by "Instance
1" (the unique name of the print
server instance).

iReport AP Extension Plugin
Introduction
The APReportExtensionsPlugin is a plugin in iReport plugin that provides

APplus specific reporting extensions. Main features provided by the
plugin are:
• Report localization support
• Support for conditional column removing
• Fix for PDF export of styled texts

• Dynamic classpath configuration
• Persistent storage of APplus specific parameters
• Statistic report helper
Setup and Configuration
The plugin is by default deployed to the lib folder of iReport by the

APplus Manager.
1. Open in the APplus Manager the module Reporting and then the tab
Jasper Integration.
2. In the section iReport activate the checkbox AP Plugin installieren

(APReportExtensionPlugin.jar).
The plugin configuration is available in iReport with the following

command iReport > Options > Configure Plugins > AP Extension Plugin.
The configuration contains the following sections:
• Company, working company
• Server information, application server address
• Report parameters, APplus specific report parameters
• Repository, local copy of report repository
Technical Description JasperReports iReport AP Extension Plugin • 49

Figure 5-1 Configuration Of AP Extension Plugin
Configuration • Typically the configuration needs to be changed when the

environment has been changed (i.e. company, location of working
copy, etc.).
• The configuration is stored to and loaded from applus.config.xml.
• The active company is stored in iReport's properties file.
• Multiple (company) configurations are stored in the same

configuration file (applus.config.xml).
• The plugin configurator can modify only existing mandatory(s). The

new (company) configuration can be created only by the APplus
Manager.
50 • iReport AP Extension Plugin Technical Description JasperReports

Server Information The AppServer Adresse is used to populate the appserver parameter
when Report Run is used to execute the report.
• Application server address has to contain the URL of the application

server.
• The format is:
http://host_name:port
e.g.
http://localhost:2037
Report Parameter • WebServer Adresse used to populate web server parameter. The
parameter contains the URL of the web server in the format
http://host_name/web_name
• User name (p2user) used to populate p2user parameter when

Report Run is used to execute the report.
• Environment (env) used to populate env parameter when Report

Run is used to execute the report.
Repository Local report directory contains the path to the local report repository.
The path is used to create absolute paths to
• shared subreports
• resource bundle files
• scriptlet library
• common style template
The classpath is updated when the configuration is saved. The classpath

can be checked in iReport with the command Options > Classpath.

Modules
APReportRunExtension is a bundle of APplus plugins for iReport. The

bundle includes:
• APReportRunExtension, iReport plugin that provides APplus specific

report execution. The plugin uses functionality provided by
• APReportLocalizerPlugin, iReport plugin that allows report

localization from iReport. It uses the APReportLocalizer utility that
substitutes static texts in reports with resource bundle keys and
creates/updates a resource bundle.
Report Run (APReportRunExtension)
Functionality • adds mandatory parameters to report parameter map
• conditional column removing
• Fix for PDF export of styled texts
• Statistic report helper
Run Reports The Report Run is available in iReport in the
• toolbar
Figure 5-2 Toolbar
• pane
Figure 5-3 Pane Of AP Extension Plugin

Mandatory Way to The Report Run is a mandatory way to execute APplus reports.
Execute APplus
Reports
In addition to regular report execution the Report Run
• adds mandatory report parameters (appserver, p2user, env) to the

report parameter map.
• exports MARKUP texts correctly, when the report is exported to

PDF.
• checks for presence of the removeColumns parameter. When the

parameter is defined it removes or displays columns based on
condition evaluation.
• automatically reads the selFields and selJoin parameters from the

file selParts.xml.
Helper Notes Helper notes for statistical reports:
• When a statistical report is executed we need to provide only the

grouping information (selGroup parameter). The selFields and
selJoin parameters are mandatory read from the file selParts.xml.
• The report name must follow the naming convention! The helper
obtains the table and analysis information from report name
(needed to get the selFields and selJoin parameter from the file
selParts.xml).
• Multiple company support requires that company specific

selParts.xml files is present in the classes folder. The file name has
to be:
selParts_<company>.xml
Report Localizer (APReportLocalizerPlugin)
Functionality • substitues static texts with text references
• substitutes text(s) in expressions with text references
• creates/updates default resource bundle
• single report or mass report localization
For detailed information about the Report Localizer see

Jasper Reports Lokalisierung".


Authoring
Some of the requirements of reporting in APplus could not be met with

the reporting components of Jasper out of the box. Some of the limi-
tations were solved with APplus specific components and configuration
files. Other limitations are solved with the help of an APplus specific
report design. The report authoring topic describes APplus specifics in
the creation process of a report that we need to be familiar with before
we start to design a report.
Document Bands (Sections)
A report is divided into different horizontal portions named bands. The

page is divided into nine predefined bands to which new groups are
added. For every group iReport manages a heading band (group
header) and a recapitulation band (group footer).
Figure 6-1 A Report divided by Bands
Technical Description JasperReports Authoring • 55

When the report is joined with the data generating the print, these
sections are printed as many times according to their function and
according to the rules that the report author has set up. For instance:
• the page header is repeated at the beginning of every page,
• the detail band is repeated for every single record.
Notes • A band is always as wide as the page width (right and left margins
excluded).
• The Band's height, even if it is established during the design phase,

can vary during the print creation according to the contained
elements; it can "lengthen" toward the bottom of a page in an
arbitrary way.
This typically occurs when bands contain subreports or text fields that
have to adapt to the content vertically.
• The height specified by the user should be considered the minimal

height of the band.
• Not all bands can be stretched dynamically according to the

content, in particular:
• the column footer,
• page footer and
• last page footer.
• The sum of all band heights (except for the background) has to
always be less than or equal to the page height minus the top and
bottom margins.
Reference A description of each of the predefined bands plus the bands for groups
can be found in the documentation The Definitive Guide to iReport™ in
Chapter 3 page 26.
56 • Authoring Technical Description JasperReports

Fonts
Default format for documents (reports) generated by Applus is PDF. To

obtain desired output as PDF we need to understand the jasper Font
properties and how Jasper rendering engine uses the fonts.
The topic "Jasper Reports Working with Fonts" describes:
• "Font Properties" on p. 113
• "Using Custom Fonts (TTF) in PDF Documents" on p. 114
• "Creating PDF Document(s) Containing Unicode Text" on p. 115
• "Creating PDF Document(s) Containing Unicode Text" on p. 115
• "Limitations and Issues" on p. 121 (when working with PDF

documents)
Styles
A report style is a collection of style settings declared at the report

level. These settings can be reused throughout the entire report
template when setting the style properties of report elements.
The topic "Styles" describes:
• "Creating a New Style" on p. 103
• how to reuse styles (see section "Reusing Styles" on p. 105)
• "Conditional Styles" on p. 104
• "APplusStyles Template" on p. 110
• "Limitations and Deficiencies" on p. 110
The description of AP standard styles and how to use them in the

reports see Technische Beschreibung Jasper Reports installieren und
administrieren and Chapter "Jasper Reports Styles".

Scriptlets and Utility Classes
Scriptlets and utility classes presents the characteristics of
• Report Scriptlets
• Utility classes
and their differences.
For detailed information about scriptlets and utility classes see

We distinguish between two types of classes,
• the ones that implement the scriptlet interface (scriptlets) and
• the ones that consume web services (utility classes).
Subreports
A subreport is a real report composed of its own XML source and

compiled in a JASPER file. To create a subreport means to create a
normal report. In the master report it is possible to insert a subreport
by using the Subreport tool.
JasperReports Built-in JasperReports provides some built-in parameters (they are internal to
Parameters the reporting engine) that are readable but not modifiable by the user.

APplus Requirements of Subreport
• The name of a subreport name must end with _sub.
• The report specific subreports are located in the same folder as the
master report and are referenced with their name with the exten-
sion jasper.
Figure 6-2 Reference To a Subreport
• The shared subreports are located in the folder shared and are
referenced with the help of a relative path in their name.
Figure 6-3 Subreports Located In the Folder shared

• Each Subreport must define Parameter Map Expression as
$P{REPORT_PARAMETERS_MAP}
• Each subreport must define Connection/Data Source Expression as
$P{REPORT_CONNECTION}
Figure 6-4 Parameterdefinition Of Subreports
Parameter Passing We have to pass AP mandatory parameters (appserver, env, p2user) to

each subreport that obtains data from the database or from web
service. And we also want to pass all other parameters received from
APplus to the subreport.
• We use the built-in parameter REPORT_PARAMETERS_MAP to pass

to the subreport the same parameters map that was provided to the
master report
• REPORT_PARAMETERS_MAP is the java.util.Map and it contains

the parameter values defined by the user.
• the expression we have to use is

$P{REPORT_PARAMETERS_MAP}.
• In addition to the report parameters, also the fields, the variables

and static texts can be passed to the subreport.
• Only data (fields, variables) that must be transferred from the

master report to the subreport is mapped to sub-report parameters
using Subreport parameters map.
Figure 6-5 Transferred Parameters From Master to Subreport
Note: Be aware that parameter names are case sensitive!

Reusing Connection We have to pass the report connection to each subreport that obtains
data from the database.
• It is possible to pass this already opened connection to the child

report by using
• the connection expression and
• the parameter REPORT_CONNECTION.
By using a connection expression, we ensure the report will be created

from the SQL query contained in the subreport.
The parameter REPORT_CONNECTION defines a java.sql.Connection

object that is already linked to the database.
Compiling Subreports
To use subreports in iReport they must first be compiled, before master

reports are able to run locally. This can happen by loading and com-
piling the relevant subreports in iReport or with the iReport plugin
Massive Compiler that can compile recursively all reports within a
directory.
Tables
JasperReports doesn't support tables as the report element. Official

mandatory are the tables that can be realized with other supported
elements.
Despite the lack of table elements we can simplify our work with tables
(to certain extent) by
• using frames as a row element (table header, table detail, table

footer),
• using bands to represent table parts (table header = group header,

table detail = detail, table footer = group footer),
• conditionally displaying or hiding columns.

Using Bands For Modeling Tables
Tables are typically composed with a table header, detail section and
table footer. In Jasper Reporting we can design a table by assigning
table elements to report bands. The common approach is to use column
or group bands as a table header and a footer.
Column The table is designed as a subreport.
The subreport should contain only three bands
• column header = table header,
• detail = table detail section,
• column footer = table footer.
The Report properties in section More… the checkbox floating column

footer must be enabled.
Example • angebotAngebotUst_sub.jrxml
Group The table is designed as a subreport.
Add a (dummy) group, e.g. table.
The subreport should contain only three bands
• group header = table header,
• detail = table detail section,
• group footer = table footer.
Example • bestellungBestellunPos_sub

Using Frames as a Row Element
We use the frame element to group elements with the same properties
(e.g. table row cells). We can set properties to a frame instead to each
element separately. The same is valid also for elements expressions.
Some examples of usage are:
• conditional row hiding,
• border drawing (between rows),
• using a style.
Example • Conditional Row Hiding
Sometimes we need to hide the entire row depending on a condition

evaluated at run time. The row should be removed from the report and
no space should remain when the fields are hidden.
• We use the frame element in a report to represent the row.
• The frame contains all row cells.
• The Print when expression defines when the frame is visible
• The Remove line when blank property defines that the line should
be removed when it is not printed.
Example: Auftrag report, auftragAuftragPos subreport
• Frames are used in columnHeader and Details bands.
• Subreports uses frames to conditionally hide rows.
• The conditional expression is used only on the frame instead of

applying it to each field in the row (we are hiding).
Conditional Displaying or Hiding Columns
Conditional column displaying or hiding can be achieved
• by altering report templates at runtime (see section "Altering

Report Templates at Runtime" on p. 131)
• with report design containing a table row for each column

combination (see section "Using Special Report Design" on p. 135)

APQE - Query Executer and Query Language
The query language used by APplus reports is apqe. The language is

associated with the APplus query executer factory (APQueryExecuter-
Factory). The factory creates four different query executers:
• (custom) SQL (see section "AP SQL Query Executer" on p. 139)
• Sel Info (see section "Sel Info Query Executer" on p. 141)
• Mandant (see section "Mandant Query Executer" on p. 143)
• Web Service (see section "Web Service Query Executer" on p. 144)
Other important APQE components and their functionality are described

in the section "Other APQE components" on p. 145)
Report Parameters
Parameters are values that are usually passed to the report from the
program that creates the print of the report. They can be used for
guiding particular behaviors during runtime (such as the application of a
condition in a SQL query) and for supplying additional data to the print
context such as the path to the images stored on the web server.
• We can use parameters in report expressions and queries.
• Example: To print information about a particular order identified

by order ID (not known at design time), we have to modify our
query as follows
WHERE bestellung=$P{docNr}
• The jasper syntax for parameters is $P{parameter}.

• The special syntax used in the query is $P!{parameter}.
• It allows to provide the query snippets at run-time
• All parameters added to the requested URL are passed to the report
engine.
• We distinguish between internal orreserved and custom or user

parameters:
• internal parameters are further subdivided to
• mandatory - used to connect to proper data source and

fetch correct data.
• optional - used to pass application or document specific

information to report server, some of them may also be
used in the report design.
• custom parameters are defined by the user and can influence the
report rendering or be used in the report design.

$P!{paramName} Syntax
Sometimes it is useful to use parameters to dynamically modify

portions of the SQL query or to pass the entire SQL query as a
parameter to the report-filling routines. In such cases the syntax differs
a little bit, $P!{paramName}.
Notice the ! character.
• This special syntax for report parameters introduces the parameter

values.
• The value supplied for such parameters replace the parameter

references in the query before it is sent to the database server.
• The reporting engine first deals with the $P!{} parameter

references by using their values to obtain the final form of the SQL
query and only after that transforms the rest of the $P{} normal
parameter references.
For example, if you have a parameter named MyWhere with the value
of where CUSTOMERID = 5, the query
select * from customers $P!{MyWhere}
will be transformed into

select * from customers where CUSTOMERID = 5
by using this syntax.

APplus Internal or Reserved Parameters
Mandatory Mandatory parameters are:
• appserver,
• p2user and
• env.
These parameters are used to create a database connection. The

connection is created by APQE and passed through the jasper engine to
fetch the data. The parameter initialization depends on the context:
• APplus - When the request of the report rendering is made by

APplus, the parameter are provided by APplus.
• iReport - When we run a report in iReport, the parameters are read

from the iReport's properties file or from applus.config.xml.
• JasperServer - When a report runs on the JasperServer the

parameter are read from applus.config.xml.
Note: Mandatory parameters don't need to be defined in the report

design.
Parameter appserver The parameter
• contains the address of the APplus applicationserver.
• is used to locate the APplus applicationserver.
• is used by APQE to get database connection string, to process

SQL queries and execute web service functions.
• is used by the web service scriptlet functions to execute web

services functions (provided by the APplus applicationserver)
Parameter env The parameter
• contains the user's environment.
• is used by APQE to
• get the proper database connection string.
• preprocess the SQL query and create the fully qualified SQL
query.

Parameter p2user The parameter
• contains the APplus internal user name (as defined in the table
PERSONAL).
• is used in the reporting context
• to obtain the environment of the current user and fetch the

correct data.
• to consume the web service functions (APQE, sciptlets, print

server).
Note: In this case the internal user name is NOT used directly.
It is converted to the windows user name prior to perform web
service calls.
Mapping of the You configure the user mapping of the windows user to the APplus user
Windows user to the in the APplus Manager with the order AppServer > User-Mapping.
APplus user
The mapping defines the content of the parameter p2user. We can
select between Active Directory and user mapping of the domain.
When UserMapping is
• set to AD (Active Directory), the user mapping is performed by

active directory. The AdUserNameMappingProperty property
contains the Active Directory property that will be used to map the
windows user to the APplus user.
• set to DefaultDomain the mapping is performed by APplus. The

DefaultDomain property contains the domain that is used together
with the user name defined in the table PERSONAL to form the
windows user name.
• not configured, the mapping is not performed. In this case it is

assumed that the internal user is equal to the windows user
(domain\username).

UserMapping Additional Property p2user (table Comment

PERSONAL)
AD AdUserNameMapping- User as defined in The property AdUserName-

Property Active Directory MappingProperty defines the
property of the Active Directory
used to map the windows user to
the APplus user.
DefaultDomain DefaultDomain Windows user The property DefaultDomain de-

without the domain fines the user's domain. The
user's domain and the user
name defined in the table
PERSONAL are joined to form the
windows user name.
none n/a Windows user in The windows user name and the
form: APplus user name must be
domain/username equal.
Where is the parameter p2user configured and what it is used for

• APplus Manager: SysConf > Reporting > Print Server, User for PS
instance, allows the filtering of print jobs. The print server
processes only the jobs created by the defined user.
• APplus Manager: Reporting > Jasper Integration, APplus Benutzer
für applus.config.xml. The user name is stored in the configuration
file for the JasperServer and iReport. The file (and the user infor-
mation) is used when we run reports on the JasperServer and in
iReport. The user name is used to obtain database connection
parameters and create connection to database.
• iReport: APExtensions Plugin > Konfiguration, User name (p2user).

The parameter is used when we run reports from iReport. When
Report is executed the parameter p2user with the defined value is
added to the report parameter map. It is used to obtain database
connection parameters and create connection to the database.
Other reserved Other reserved parameters are:

parameters
Parameter Name Description Reporty type
docNr The document ID documents
docName The name of the document documents
docFormat The document format (e.g. PDF, RTF, etc.) documents
docLang The language used in the document (locale) documents
docTable The base table containing the document data documents
docRptPath The path to the report in the JasperServer documents

repository
docId The record ID documents
docPages The number of print copies documents
docPrinter The printer used to print the document documents
webname The name of the web (e.g. Trunk) all

Parameter Name Description Reporty type
servername The name of the server hosting the web (e.g. all
virtualpc)
webserver The web URL (e.g. http://virtualpc/Trunk) all
where Passing the search or filtering criteria at run statistics

time
orderby Passing the sort criteria at run time statistics
selGroup Passing the grouping criteria at run time statistics
selFields Passing the query snippets (query fields) at statistics

run time
selJoin Passing the query snippets (join statements) statistics

at run time
noclient statistics
Parameter WHERE The parameter where is an APplus internal or reserved parameter.

When the parameter is present in the SQL query, it triggers a special
processing in APQE. It is used by statistic and list reports to define and
pass search or filtering criteria at run time.
• The filter is defined as a collection of key-value pairs assigned to

the parameter where.
where=ARTIKELGRUPPE%3D[1000;]%26DATUM%3D[2003-10-
05T00%253A00%253A00;2009-10-
05T23%253A59%253A59]%26WAEHRUNG%3DEUR
• The keys have to be field names from DB tables or views.
• The values can be ordinal values or ranges, e.g.
DATUM=[2003-10-05T00%3A00%3A00;2009-10-
05T23%3A59%3A59]
WAEHRUNG=EUR
• The APQE converts the value of the parameter where to search

criteria in SQL syntax, e.g.
WHERE ( ( ( t.DATUM >= N'2003-10-05T00:00:00' AND t.DATUM <= N'2009-10-05T23:59:59' )
) AND
( ( t.ARTIKELGRUPPE >= N'1000' ) ) AND
( t.WAEHRUNG = N'EUR' ) )
• Multiple conditions are joined with AND in search criteria.
Usage in SQL query:

[WHERE [<search criteria in SQL-Syntax> AND] $P{where}]

Usage in statistical Statistical reports use Sel-pages to create a selection filter.

reports
The elements (fields, checkbox, etc.) on a Sel page are basically divided
in two categories:
• one that have names equal to field names of tables in the database.
• one that are not named as field names of tables in the database.
• When the report is previewed or printed:
• the user input for the statistical analysis is collected,
• a collection of key=value pair is constructed (selectedFields(),

selUtils.js),
• the collections is assigned to the report parameter WHERE,
• the elements with names ending with "_" are added to the URL also
as distinct report parameters (getExtendedReportParam(),
selUtils.js),
• all parameters that are part of URL are passed to the report,
• on the JasperServer APQE performs the preprocessing on the

WHERE parameter and constructs a fully qualified SQL query.
APQE APQE has a special handling for the parameter WHERE (collection of
key=value pairs):
• it removes all keys that start or end with "_", the exception is
_BDATUM,
• it removes the following keys: accessed, view, order and sort,
• it assumes that other keys are valid field names in the database
and creates a search criteria in SQL syntax,
• it removes the WHERE sentence (from the query) when the

parameter where is not defined (and is the only condition in
WHERE, i.e. WHERE $P{where})

Passing search or Passing search or filtering criteria at run time (for non statistical re-
filtering criteria ports):
Background • the search criteria are defined at run time,
• the report uses these criteria to represent data.
Solutions Solution A:
• Use the same approach as for statistical reports.
• Make sure that the syntax of the where parameter is correct.
• Example: All (list) reports in the folder masterdata/documents
• Solution B:
• Use the special syntax of jasper for query parameters.
• The parameter name must NOT be: where.
• Use the parameter $P!{myWhere} in place of the WHERE statement

SELECT * FROM table $P!{mywhere} -> $P!{mywhere}: WHERE field = 'P123'
or (if we are sure that parameters will be always defined)

SELECT * FROM table WHERE $P!{mywhere} -> $P!{mywhere}: field = 'P123'
Parameter orderby The parameter orderby is an APplus internal or reserved parameter.

When the parameter is part of the SQL query, it triggers a special
processing in APQE.
Purpose The purpose used by statistical reports is to define and pass selected
sort order by the user.
Usage Usage in the SQL query:

[ORDER BY [<columns in SQL Syntax>,] [$P{orderby}]
APQE has a special handling for the parameter ORDERBY:
• it removes the ORDER BY sentence (from the SQL query) when the
parameter orderby is not defined (and is the only sort criteria, i.e.
ORDER BY $P{orderby})
Parameters selGroup, • The parameters selGroup, selFields, selJoin are used in statistical
selFields, selJoin reports.
• They provide the grouping and grouping specific SQL query snippets
from the webserver.
• The parameters are populated by the web server
• The values for the selFields and selJoin parameters are obtained
from SelParts.xml (see section "SelParts.xml" on p. 27).
• The value for the selGroup parameter is obtained on the Sel

page
• The parameters selFields and selJoin are statement parameters

($P!{parameter}) (see section "$P!{paramName} Syntax" on p. 65
in this chapter).
• The parameter selGroup is a regular parameter.

• The parameters selGroup, selFields and selJoin are defined only
when statistical page supports multiple groupings.

• The parameter selFields and selJoin can be empty (when the

grouping doesn't require a SQL query modification).
• For detailed information how you can define the parameters

selGroup, selFields, selJoin parameters see Schulungshandbuch
APplus Jasper Reports and Chapter "Reports für statistische
Auswertungen".
Custom or User Parameters
The custom parameters are defined by the user and can influence the
rendering of the report or can be displayed in the report. The user
usually has to
• provide the functionality for the parameter collection on the

webserver (e.g. a dialog, a field on page, etc.).
• make sure that the parameter is passed to the print or preview URL
request.
More Information about passing custom parameters from APplus can be

found in:
• How to pass custom parameters to statistic reports (see section "...

Pass Custom Parameters to Report?" on p. 34).
• How to pass custom parameters to doc, list, out reports (see

section "... Pass Custom Parameters to a Report?" on p. 39).

Organization Of the Repository
• The repository of reports has the same hierarchy as the webserver.
• The repository contains folders representing modules and a shared

folder.
• The folder, containing the reports of a module, is further devided to

documents and statistics.
• the folder documents contains all documents, i.e. doc, out and
master data reports.
• the folder statistic contains statistical reports.
• The folder shared contains the resources, that are shared between
reports, e.g. subreports, resource bundle, style and scriptlets.
• The report path in the epository is generated automatically. It is

therefore mandatory to save the report to the correct folder in the
report repository hierarchy.
Hierarchal Structure of the Folders
modul1
|--documents
| |--reportname01
| |--reportname02
| |--reportname02_sub
| |--reportname02Subname_sub
| |--subname_sub
|
|--statistics
| |--reportname01
|
modul2
|
Shared
|--subreports

Figure 6-6 Hierarchal Structure of the Folders
Definitions Definitions of the reporting structure:
• Name of the modul: name and label = beginning with a lower case
letter (e.g. "automotive").
• The folder of a module has always the folders documents and

statistics as subfolders.
You can always identify reports for statistical analysis that they
• Were used on Sel pages or were used by functions, who

prepared the selection criteria for statistical analysis.
• the selected criteria by the user will be shown in the header of a

report (and lists the selection criteria).
• Storage of subreports:
• If a subreport is used by several reports, the subreport has to

be stored in the folder /shared/subreports.
• If a subreport will be used just by a single master report, the

subreport has to be stored in the same folder as the master
report.

Difference between iReport and JasperServer repository
Topic iReport JasperServer
Report structure Master report is separated from its Report units are used to represent
resources. The resources are reports in the server. The report unit
spread in the repository depending is a container that contains the
on their type (resource bundle, master report, input controls and
image, subreport, etc.) and usage resources. Input controls folder
(local, shared). contains controls needed to enter
report parameters (via web
interface). The resources folder
contains local subreports and explicit
resource reference links.
Report compiling The master report and all its The master report and all its
subreports (local and shared) subreports are compiled by the
must be compiled prior to the re- server on the fly when the report is
port execution. Only the master executed (run).
report is compiled during report
execution (run).
Report referencing • The resource bundles (folder • The resource bundles

bundles) and utility functions (ApplusReportTexts.properties,
(jar/APReportsScriptlets.jar) ApplusReportTexts_en.properties
are added to the classpath in , etc.) and utility functions
iReport. (APReportsScriptlets) are added
• Images, styles and shared to the report unit as a resource
subreports are referenced with reference.
relative paths from the root • Images, styles and shared sub-
folder of the repository, e.g. reports are referenced with the
"/shared/styles/Applus- absolute paths from the root
Styles.jrtx" folder of the repository, e.g.
• The resource names must "repo:/Reports/Trunk/shared/sty
have file extensions, e.g. les/ApplusStyles".
appluslogo.gif, • The resource names don´t have
ApplusStyles.jrtx, a file extension, e.g. appluslogo,
StandardTitle_sub.jasper ApplusStyles, StandardTitle_sub.
Note. The resource bundles are
exception, because their names
must have the extension
.properties.
Input controls N/A The input Control is a server

resource that is used as an interface
that allows user to enter the report
parameters. The input control must
be created for each parameter that
is mandatory for a report.

Naming Convention
Naming Convention of Reports
Master Report • Name of the table (in lower cases)
• Topic of the document (to begin with a upper case letter)
• WITHOUT name of the module und WITHOUT typ (List, Out or Doc).
The affiliation to the module and to the type will be figured through
the hierarchy of the folders, e.g. bestellungBestellung.jrxml.
Subreport • Subreports and master reports are subject of the same naming con-
vention, but plus topic plus "_sub" or
• topic plus "_sub".
The name of a table is necessary, because there exists reports with the
same name, which are stored in the same directory but refer to differ-
ent tables, e.g. "Mahnung".
The limitation of length of 32 characters for resources in the Jasper-

Server repository was with JasperServer 3.0 removed.
Documents, Lists, Out
• Master reports: tableDocumentOther
• Subreports: tabelleDocumentOtherSubreportname_sub or topic_sub
Terms • table – name of the table (anfrage, angebot, auftrag,

bestellung, rechnung, etc.)
• Document – name of the document (Bestellung, Mahnung,

Erinnerung, Korrektur, etc.)
• Other – Optional Text (e.g. "alle Pos", Serie, DIN4994)
• Subreportname – only for Subreports, short name of the local

subreports (e.g. Pos, Ust, Pospos, Detail, etc.)
Statistical Analysis
• Master reports: tableAnalysis
• Subreports: tableAnalysisSubreportname_sub oder topic_sub
Terms • table – name of the table
• Analysis – Typ (z.B. Kurz, Lang, Obligo, Offenelief, Rechnung,

Monate, etc.)
• subreportname – only for subreports, short name of the local

subreports

Examples
before after
purchaseBestellungArtikelgruppeKurzList bestellungKurz
AplanOut aplanArbeitsplan
PeriodAbschlOut personalPeriodAbschl
Name Of the Name of the document subreport: = name of the parent report +
Document "_sub"
or
topic of the subreport + "_sub"
Example • personalPeriodAbschlDetail_sub,
• lieferabrufinLieferliste_sub,
• wauftragKopf_sub
Report Types
We distinguish between the following report types:
• document – business documents, e.g. invoice, order, etc.
• list – master data list, e.g. company list, person list, etc.
• out – free form report, e.g. stickers
• statistic - statistic reports, used to present data analysis,

calculations
The report type influences
• the print or preview flow on the webserver
• the report parameter collection and handling on the webserver
• the naming convention used for reports
• documents, lists, out (see section "Documents, Lists, Out" on

p. 76)
• statistical analysis (see section "Statistical Analysis" on p. 76)
• location of the report in the repository (see section "Organization Of

the Repository" on p. 73)
• report integration
• documents, lists, out (see section "Other Reports (Documents,

Lists, Out)" on p. 35)
• statistical analysis (see section "Statistical Reports" on p. 25)
• selection of internal parameters

Standard Report Templates
In the folder
/reports/<Company>/shared/templates
you find several templates you can use as a starting point to build new
reports (and subreports):
• ApplusReportTemplateBasic
• ApplusReportTemplateStandardDoc
• ApplusReportTemplateStandardList
• ApplusReportTemplateTablenameKurzDetail

Jasper Report Internationalization
Users have different cultural expectations and speak different

languages. JasperReports internationalization features make it easier to
adapt reports to different countries and regions. Creating a global
report isn't particularly difficult, but it does require us to become
familiar with the most common international problems and their
solutions.
Internationalization and Localization
• Internationalization is the process of designing a report so that it

can be adapted to various languages without engineering changes.
• Localization is the process of adapting internationalized report for a

specific language by adding locale-specific elements and translating
text.
During these processes
• we identify the locale dependant fields (e.g. numbers, date, time,

etc.) and make them adaptable to locale options used to build the
report.
• we make all the static text set at design time (such as labels and
messages) adaptable to locale options used to build the report.
• we design or implement a way to provide the locale information to

the rendering engine.
• we translate texts (resource bundles).
Technical Description JasperReports Jasper Report Internationalization • 79

Providing the Locale Information
Usage of Locales Locales are used throughout the reports to customize how data is
presented and formatted. They affect language choice, collation,
calendar usage, date and time formats, number and currency formats,
and many other culturally sensitive data representations.
Locale A locale is a relatively simple object. It identifies a specific language

and a geographic region.
We need to provide the locale to the report rendering engine. The

JasperReports engine uses a built-in parameter REPORT_LOCALE for
localization purposes. The engine uses this parameter to
• format all locale dependent data in the report.
• select proper resource bundle file.
• Details about setting the REPORT_LOCALE parameter are explained

in:
• How is the locale report set in APplus (for detailed information see
"… in APplus" on p. 91)?
• How is the locale report set in iReport (for detailed information see
"… in iReport" on p. 93)?
• How is the locale report set in Jasper Server (for detailed

information see "… in JasperServer" on p. 94)?
Making Locale Dependent Fields Adaptable to Locale

Options (Culture Sensitive Formatting)
Cultural preferences are not always immediately comprehensible.

Dates, time, numbers and currency are all examples of data which are
formatted according to cultural expectations. Cultural preferences are
tightly coupled to a geographic area.
Numbers Numbers are represented differently around the globe. When an

application shows a number to the user, it must represent that number
in a way that is sensitive to the cultural expectations regarding decimal
point symbol, group separators, number of digits after the decimal and
leading zeros.
Currency Each locale has its own preferences for currency symbols, negative
amount format, leading zeros, group separators, decimal point symbol,
and currency symbol position.
80 • Jasper Report Internationalization Technical Description JasperReports

Date and Time Like other locale-sensitive structures, dates have many representation
details. We must consider long and short date formats as well as date
separator symbols. We have to worry about whether the year is
displayed before the day and month or after.
Details about how to make locale dependent fields adaptable to locale

options are described in:
• How to perform Culture-sensitive Formatting (for detailed

information see "How to Perform Culture-sensitive Formatting?" on
p. 86)
• APplus standard formatting (for detailed information see "APplus

Standard Formatting" on p. 88)
• Custom formatting (for detailed information see "Custom

Formatting" on p. 89)
Making Static Texts Adaptable to Locale Options
Localizing a report means making all static text set at design time (such
as labels and messages) adaptable to locale options used to build the
report. The report engine will print the text using the most appropriate
available translation. The text translations in the different languages
supported by the report are stored in particular resource files
collectively named the Resource Bundle.
Resource Bundle
Caveat You'll need to understand following caveat regarding resource bundles:
• you must create Resource bundles in ASCII,
• use Unicode escape codes to represent Unicode characters.

Since we don't compile a resource bundle file to byte codes, there is no
way to tell the Java Virtual Machine (JVM) which character set to use.
So we must explicitly stick with ASCII or use the escape sequences. We
can represent a Unicode character in any Java file using
\uXXXX
where
XXXX
is the hexadecimal representation of the character.
Note: JDK provides the native2ascii tool that converts a file written in
native encoding to one that represents non-ASCII characters as Unicode
escape sequences.

Limitations of Native
Localization Support iReport supports report localization. In order to use this functionality
in iReport the following requirements must be met:
• A resource bundle file must be created for each report or subreport.
• Resource bundle files must have the same name as the report files
(except for file extension).
• Resource bundle files must be stored in the same directory as the

report files.
This approach has following limitations:
• The resource files are spread across the repository, which is difficult
to maintain.
• The same text can be spread in multiple files, the corrections has to
be done in multiple files.
Custom Localization Support
The iReport's localization support is not used. Instead we use the

custom tools to localize reports and deploy them to JasperServer.
• The Localizer and Mass Localizer (which are part of the AP

Extension Plugin for iReport) are used to
• convert text (Static Texts and Text Field Expressions) to

references (for more information see "How Do We Localize
Texts in Reports?" on p. 96).
• create or update default resource bundle (for more information

see "How to Create or Update a Default Resource Bundle?" on
p. 95).
• The AP Extension Plugin is used to add resource bundles to the

class path.
• The Reporting or Repository plug-in of the APplus Manager is used

to
• deploy reports and bundles to report repository on the

JasperServer (for more information see "How To Deploy a
Report and Resource Bundle(s)?" on p. 96).
• The Übersetzung plug-in of the APplus Manager is a resource bundle

editor. It is used to
• create the language resource bundle files.
• edit or translate the default resource bundle to other languages
For more information see "How to Create or Update or Translate the

Resource Bundle for a New Language?" on p. 95.

Benefits • One resource bundle that contains texts from all reports. The
Translator gets one resource file instead of many.
• Texts are not duplicated. The changes are reflected immediately in

all reports (since some reports share the same texts).
• one (predefined) base resource bundle name, ApplusReportTexts
• Single place where corrections are performed.
• The resource bundle is stored in the shared directory
ApplusJReports/shared/bundles
• Easier to maintain and manage.
Requirements We need to use custom tools in order to create and use localized
reports (in iReport, JasperServer and APplus). We have to make sure
that the following requirements are met:
• Resource bundle base name must be defined in report properties.
• Resource bundles must be in the classpath.
• Reports deployed to the Jasper Server repository must reference

the resource bundles in the shared folder of the repository.
• Resource bundles must be created in ASCII and use Unicode escape

codes to represent Unicode characters Resource Bundle caveat (see
"Resource Bundle Caveat" on p. 81)!

Additional Information
The chapter "Jasper Report Internalization Q&A" provides some more

infomation about
• localization steps (for more information see "How Can I Localize a

Report?" on p. 85),
• culture-sensitive formatting (for more information see "How to

Perform Culture-sensitive Formatting?" on p. 86),
• setting report locale (for more information see "How Is the

Localization of a Report Set …" on p. 91),
• resource bundle creation (for more information see "How to Create

or Update a Default Resource Bundle?" on p. 95),
• creating, updating, translating resource bundle for a new language

(for more information see "How to Create or Update or Translate
the Resource Bundle for a New Language?" on p. 95),
• report text localization (for more information see "How Do We
Localize Texts in Reports?" on p. 96),
• report and bundle deployment (for more information see "How To

Deploy a Report and Resource Bundle(s)?" on p. 96),
• report language selection on Jasper server (for more information

see "How to Select the Report Language on the JasperServer?" on
p. 98),
• language selection for printed documents (for more information see

"How to Select a Language for Printed Documents?" on p. 100),
• language selection for previewed documents (for more information

see "How to Select a Language for Previewed Documents?" on
p. 102).

Jasper Report Internalization Q&A
How Can I Localize a Report?
Report Design
1. Design a report considering the culture-sensitive formatting.
2. Use the Localizer tool to convert static texts and update the resource
bundle file.
3. Define supported languages in document's print job definition in the file

DocTypes.xml.
Verify Report
1. Deploy the report and the bundle(s) to the JasperServer.
2. Check that the report is rendered correctly on the JasperServer (use

different languages).
3. Print the report in different languages.
4. Preview the report in different languages, if it´s applicable.
Technical Description JasperReports Jasper Report Internalization Q&A • 85

How to Perform Culture-sensitive Formatting?
In order to consider locale options in the report designs, it is necessary

that fields use culture-sensitive formatting. The locale dependant fields
are the ones that display
• date,
• time,
• numbers and
• currency.
Note: Not all currency fields must change according to locale

options, e.g. we shouldn't make a currency field in the invoice data
section locale dependant.
In most of the cases we can achieve the desired formatting

• by entering the format string directly to the Pattern dropdown list
box or
Figure 8-1 Enter the Format String
86 • Jasper Report Internalization Q&A Technical Description JasperReports

• by using the Pattern editor for this purpose you had to click on the
Create… button, where you can select a pattern from predefined
ones.
Figure 8-2 Select a Pattern Form Predefined Patterns

APplus Standard Formatting
Date To determine the standard formatting of date fields you had to write in
the Pattern dropdown list manually
short,hide
Figure 8-3 Pattern Formatting Strings
Numbers To determine the standard formatting of number fields you can select
the predefined pattern
#,##0.00;-#,##0.00
Figure 8-4 Predefined Pattern Of Numbers

Custom Formatting
When we need to have more flexibility for field formatting, we can

resort to java formatting functions. You can use the java
DateFormat []
class to format date or time, see also
http://java.sun.com/j2se/1.4.2/docs/api/java/text/DateFormat.html
To format numbers, currency, percentage you can use the java

NumberFormat class, see also
http://java.sun.com/j2se/1.4.2/docs/api/java/text/NumberFormat.html
Required Text Field If you want to change the properties of a text field, you had to do the
Properties following:
1. Open the dialog to change the element properties of a text field and
than open the Text Field tab.
2. Select in the Text Field Expression Class dropdown list java.lang.String.

3. Leave the Pattern dropdownlist blank.
4. To the field Text Field Expression enter the appropriate java class
depending on the data you are formatting (see examples bellow).
Date Formatting For formatting date fields use the method
getDateInstance()
to get the date format for the provided locale ($P{REPORT_LOCALE}).

Write the following expression in the field Text Field Expression
DateFormat.getDateInstance(DateFormat.SHORT, $P{REPORT_LOCALE}).format($F{datum})
where the class type of $F{datum} is Timestamp.
Time Formatting For formatting time fields use the method
getTimeInstance()
to get the time format for provided locale ($P{REPORT_LOCALE}).
Write the following expression in the field Text Field Expression

DateFormat.getTimeInstance(DateFormat.SHORT, $P{REPORT_LOCALE}).format($F{datum})
where the class type of $F{datum} is Timestamp.

Number Formatting Use the method
getNumberInstance()
to get the normal number format or use the method
getIntegerInstance()
to get an integer number format. To format number according to a

Locale, we have to use following expression in the field Text Field
Expression:
NumberFormat.getNumberInstance($P{REPORT_LOCALE}).format($F{menge}.doubleValue())
or
NumberFormat.getIntegerInstance ($P{REPORT_LOCALE}).format($F{menge}.doubleValue())
where the class type of $F{menge} is BigDecimal.
Percent Formatting Use the method
getPercentInstance()
to get a format for displaying percentages. With this format, a fraction

like 0.53 is displayed as 53%.
For example, to format number as a percentage according to a Locale,

we have to use following expression in the field Text Field Expression
NumberFormat.getPercentInstance($P{REPORT_LOCALE}).format($F{ust}.doubleValue()/100)
where the class type of $F{ust} is BigDecimal.
Currency Formatting Use the method
getCurrencyInstance()
to get the currency number format. For example, to format number as

a currency according to a locale, we have to use following expression in
the field Text Field Expression
NumberFormat.getCurrencyInstance($P{REPORT_LOCALE}).format($F{NETTO}.doubleValue())
where the class type of $F{NETTO} is BigDecimal.

How Is the Localization of a Report Set …
… in APplus
The REPORT_LOCALE parameter is defined, when the user selects the

print or preview operation and the rendering request of the report is
created. The parameter is set differently based on operation and
document type.
REPORT_LOCALE
Parameter
Report Type
Statistical Analysis Other (Doc, List,
Out)
Operation Print language preferences print dialog
Type
for the browser
Preview language preferences table, SPRACHE
for the browser
Doc-, List-, Out Reports
PREVIEW For the operation to preview a document it is not possible to select the
document language.
• Documents defined in the file DocTypes.xml are based on tables

that have a SPRACHE column.
Note: There exist some exceptions of tables, i.e. the tables

containing master data, having no SPRACHE column.
• The document language is set to the one defined in the SPRACHE

column.
• When there is no SPRACHE column (or it is undefined) the language

is set to German.
• The language is stored in the report parameter docLang.

• The parameter docLang is copied to the REPORT_LOCALE parameter
and passed to the JasperServer.
Note: The locale object is composed of a specific language and a

geographic region, but in APplus only the language part is used (the
country is left undefined).

The language used to preview a document is set on Rec-pages on the

tab Info with the dropdown list Sprache.
Figure 8-5 Select the Language For the Document Preview
Hint: To preview the document in a different language, use the print

operation and set the number of copies to 0. The print job will be
created in the JOB table. There we can use jobURL link to view the
document.
PRINT For the print operation we can define, that the user is prompted to
select a language for the printed document.
Enabling the Selection of the Document Language
1. Open on the web server the file
WebObjects\DocTypes.xml
2. Edit or create a jobType node that defines the print job for the docu-
ment.
3. Set the value of the PrintDialog attribute to true
4. Add a jobDotFile node for each language that had to be supported.

<jobType id="Bestellung (JR PDF)" title="Bestellung (PDF)"
PrintDialog="true">
<jobPrinter>
</jobPrinter>
<jobDotFile language="de">bestellungBestellung</jobDotFile>
<jobDotFile language="en">bestellungBestellung</jobDotFile>
<archiv>/archive/bestellung/</archiv>
</jobType>
Notes: When a document is printed and the PrintDialog attribute is set

to false, the SPRACHE column of the table is used to define the
language of the report in use. The language attribute (<jobDotFile
language="de">) is not considered.
The resource bundles for all supported languages must exist and have
to contain translated texts from the report (and its subreports) in order
to get the translated version of the report.

Statistical Reports
Print and Preview Reports for statistical analysis are based on views.
• Views don’t have a SPRACHE column.
• The parameter docLang is not used.
• The language for statistical analyses is defined with the user’s

language preference for the browser.
• The browser language is set to the parameter REPORT_LOCALE and

passed to the JasperServer.
… in iReport
During the design phase we might need to change the locale to check
how locale dependent data are rendered.
1. You can change the locale in iReport with the command Build > Set
Report Locale.
Figure 8-6 Change the Locale In iReport

… in JasperServer
When we run reports on the JasperServer, the locale of the server is

used of the parameter REPORT_LOCALE.
We can change the server's locale on the welcome page.
1. In the Login prompt select the link Show locale & timezone
Figure 8-7 Show the Locale
2. Change the selected language in the dropdown menu Locale:
Figure 8-8 Change the Selected Language

How to Create or Update a Default Resource Bundle?
The default resource bundle file is created or updated by the Localizer

tool, when the reports are localized.
How to Create or Update or Translate the Resource Bundle

for a New Language?
Resource bundle files have to be edited and managed with a editor that
performs automatic native2ascii conversion. The public available tools
are
• NetBeans,
• PrbEditor and
• Zaval Java Resource Editor

that support this functionality were evaluated, but each of them had
some limitation that prevented flawless usage.
To create and edit language resource bundle files you are using the
Übersetzung plug-in of the APplus Manager.
Adding or Creating a Resource File of a New Language
1. In the APplus Manager select the plug-in Übersetzung.
2. Click on the button Laden… and select the option Reporting.
3. Select Neue Sprachvariante…
4. Enter in the field Sprachkürzel the ISO Code of the language, e. g. en,
en_US, ….
• a new column is added to the list and
• anew (empty) resource bundle file is created.
Edit or Tanslate a Resource File
1. Select in the APplus Manager the plug-in Übersetzung.
2. Click on the button Laden… and select the option Reporting.
All available languages are displayed as columns.
3. Select in the column of the desired language and edit in the row
containing the text you want to translate.
4. Edit or translate the text in the field Ausgewählter Text.

How Do We Localize Texts in Reports?
We use the Localizer and Mass Localizer to convert report texts to the
references.
For detailed information about the Report Localizer see Schulungshand-

buch APplus Jasper Reports and Chapter "Anhang 2: Jasper Reports
Lokalisierung".
How To Deploy a Report and Resource Bundle(s)?
To render localized reports from APplus or in JasperServer, the reports

and resource bundles files must be deployed to the JasperServer. The
reports are deployed as report units that contain references to resource
bundle files located in the shared folder in the repository, e.g.
ApplusJReports/shared
We use the APplus Manager to deploy reports and resource bundles files
to the JasperServer.
Note: Whenever a report is newly localized or updated (due to

localization changes) we need to transfer the report and resource
bundle file(s) to the JasperServer.
Deploy a Report To the JasperServer
1. Open in the APplus Manager the plugin Reporting and the tab
Repository.
2. Click on the Button Übertragen.
3. Select the master report from the repository.

Deploy a Resource Bundle to the JasperServer
1. Open in the APplus Manager the plugin Reporting and the tab
Repository.
3. Select the shared/bundles folder in the repository.
Figure 8-9 Deploy Resource Bundles To the JasperServer

How to Select the Report Language on the JasperServer?
1. Go to the Welcome page of the JasperServer.
2. Expand the section Show locale & timezone.
3. Check the setting of Locale.
Figure 8-10 Change the Local Setting Of the JasperServer
4. Login to the JasperServer.
5. To run a report, click on the button View and select the option
Repository.
6. Open the folder Reports and then the folders <CompanyName> with
your company name and <module> documents.
7. Select your report.
Figure 8-11 Select Reports

8. Enter the values of the report parameters p2user, env, docNr.
Report is rendered in language choosen on the JasperServer Login

page.
9. Now you can log out.
10. To change again the locale setting on the welcome page of the
JasperServer click on the button Show locale & time zone and change
the selected language, i.e. to German.
Figure 8-12 Change the Selected Language
11. Login and run the same report.
The Report is rendered in the selected language.

How to Select a Language for Printed Documents?
In order to be able to select a language for a printed document we have

to define the print job in the DocTypes.xml file properly.
1. You must edit or create a jobType node that defines the print job for
the document.
2. Set the value of the PrintDialog attribute to true.
3. Add the node jobDotFile for each language that has to be supported.
4. Set the value of the language attribute. The value must correspond to
the language code
Notes: When the document is printed and the attribute PrintDialog is

set to false the SPRACHE column (of document's table) is used to define
the language used by the report. The language attribute (<jobDotFile
language="de">) is not to be considered.
The resource bundles for all supported languages must exist and have
to contain translated texts from the report (and its subreports) in order
to get the translated version of the report.
Example Selection of the Language When Printing the Bestellung

Document
Here is the definition of the print job in the file DocTypes.xml:

<jobType id="Bestellung (JR PDF)" title="Bestellung (PDF)"
PrintDialog="true">
<jobPrinter>
</jobPrinter>
<jobDotFile language="de">bestellungBestellung</jobDotFile>
<jobDotFile language="en">bestellungBestellung</jobDotFile>
<archiv>/archive/bestellung/</archiv>
</jobType>

Print a Document in APplus
1. Open APplus and open the page Edit order in APway with the command
purchase > order > edit order and select an order.
2. To print the order, you had to click in the toolbar on the button Print
and then select Bestellung (PDF).
The print dialog pops up
3. Select language for document: Sprache
Figure 8-13 Select the Language Of the Printed Document
The print job is created in JOB table
Figure 8-14 Print Job In the JOB Table
Notes: Print Server (ApplusPrintService) must be running in order to

print the document or you can view the result by following the JobUrl
link.
The document is rendered in the language you had choosen in the print
dialog.

How to Select a Language for Previewed Documents?
To preview a document it is not possible to select a document language.

The document's language will always be the language specified in the
SPRACHE column of the document's table.
To see which language will be used for previewing a document:
1. Open the tab Info tab on a Rec-Page, where you can preview a
document, and show which language is selected in the dropdown menu
Sprache.
Figure 8-15 Selected Language On the Info tab
However, if the document can be printed in different languages, we can

use following steps to preview document in different language:
1. To print the order, you had to click in the toolbar on the button Print
and then select Bestellung (PDF).
The print dialog pops up.
2. Select the language for document: Sprache.
3. Set the Number of copies to 0.
Figure 8-16 Select the Language
The print job is created in the JOB table.
Figure 8-17 JOB Table
We can preview the document by following the JobUrl link
The document is rendered in the language selected in the print dialog.

Styles
What Is a Report A report style is a collection of style settings declared at the report
Style? level. These settings can be reused throughout the entire report
template when setting the style properties of report elements.
Example Each text element present on the report can have its own font settings.
Since a report usually uses only a few types of fonts shared by different
text elements, there’s no point to specify the same font settings re-
peatedly for each text element. Instead we reference a font declaration
in a style and adjust only some of the font settings on the spot, if a
particular text element requires it.
Creating a New Style
Define a New Style
1. To define a new style select in iReport Format > Styles.
iReport opens the dialog style.
2. In the dialog Styles press the New button to add a new style.
This opens a Style definition dialog where we can define a new style.
Figure 9-1 Dialog Add/modify Style
Technical Description JasperReports Styles • 103

Style Name The field Style name is the only mandatory field in the dialog
Add/modify style. All other fields are optional.
Default Report Style The Default style field defines a style to be the default style of a report.
If a default style is present, all the element properties that have an
unspecified value will implicitly inherit a value from the default style.
Cascading Report The Parent style field specifies the name of the parent report style.
Styles Each report style definition can reference another style definition from
which it will inherit some or all of its properties.
Conditional Styles
Instead of "normal" styles you can also use in Jasper Reports so called
conditional styles. Conditional styles are styles, which are used when a
field has a special value or when a particular position in a subreport is
achieved.
Meanwhile it´s impossible to implement conditional styles as global
styles, so therefore you had to realize a conditional style manually.
It´s easy to define a conditional style.
1. Open the docking pane Styles Library with the command View >
Docking panes > Styles
2. Select in the dropdown menu Report Styles.
3. Move the cursor in the window of the docking pane and use right
mouseclick and select the option New Style.
iReport opens the Add/modify style dialog.
4. Click on the button Add. Then you must add a new condition to the
style.
5. Define the expression, which should apply for this style and click the
button Apply.
6. Select the expression in Style Conditions and change the style.

Each expression has it´s own style!
Figure 9-2 Conditional Style
104 • Styles Technical Description JasperReports

If the expression is true, the defined style is used instead of the default
style.
It´s possible to specify several of these styles.
In the next figure you can see, that the value is represented in red, if
the value is 0.
Figure 9-3 Usage Of Conditional Style
Reusing Styles
The Styles Library
Defining Styles Instead of repeatedly defining similar styles for each report, we define a
style in the Styles library and reuse it in other reports. To use a style
from the library, we drag a style from the library over an element. If
the style is not yet present in the report, it is copied to the report from
the library (added as a report style), and the Style attribute of the
element is set to the name of the selected style.
Note: The deficiency of this approach is once a library style has been
applied to a report, any later changes to that library style will not be
updated in the report style. To overcome this issue we use styles
defined in the Style Template file.

The Style Template
The style templates provides support for reusable report styles. Styles
are stored in separate files, so called Style templates. The templates
have .jrtx extension. The Template file can include another template
file.
The styles defined in the template are shared between all reports that
use the template. We have a central place where styles are defined and
managed. The changed style in the Style temple is visible in all reports
that use the template.
To use a style from template in the report, we first have to add a

reference to the template in the report.
Note: When an attribute of an element is explicitly defined, the style

value is overridden and the style is not applied.
Creating the Style Creating a Style template and adding a style to it is easy.
Template
1. Make sure that the Styles Library pane is visible.
Figure 9-4 Docking Pane Styles Library
2. Switch in the docking pane Styles Library to the Styles library view.
Figure 9-5 View Styles library

3. Move the mousecursor on the pane and use a right click and select the
option New Jasper Template.
Figure 9-6 Use a Jasper Template
4. Select the location and name of the template.
The Style template appears as a folder in the Styles library view
Figure 9-7 Style Template

Adding a Style to the

Style Template
1. Right click on the folder and select the option Add Style to Jasper
Template.
Figure 9-8 Add a Style to Jasper Template
iReport opens the Add/modify style dialog.
2. Create a style.
The only mandatory parameter is Style name.
3. Confirm the style changes with OK.
The new Style appears in the Style template folder
Figure 9-9 New Style Appears In the Style Template Folder

Using a Style from the

Style Template
1. You can use a style with drag and drop the style from the Styles library
view to the static Text (or Text fields) in the report.
Figure 9-10 Usage Of Styles
The changes should be visible immediately.
2. Verify that the style was applied to the element.
On the Common tab on the properties dialog of the element you can
see the style in the dropdown menu Style used by the element.
Figure 9-11 Used Style by the Element

Notes When a style is applied to the report element, the style and template
references are added to report.
Change the view form Styles Library to Report styles.
Figure 9-12 Adding Style and Template Reference to a report
The absolute path is used for the template reference!
APplusStyles Template
All APplus reports must use the Style template. The template is stored
in the shared part of the repository
"…/ApplusJReports/shared/styles/ApplusStyles.jrtx"
The main purpose of the template is to have a central place where

styles are defined and managed. All reports use styles from the Style
template, so any change made to the style in the template is
immediately reflected in all reports.
Which styles are defined in the Style template and how they are used in
the reports is described in Technische Beschreibung Jasper Reports
installieren und administrieren and Chapter "Jasper Reports Styles". The
topic also describe how to use the Style template in iReport.
Limitations and Deficiencies
• Conditional styles are not supported in the Style template.
• WYSIWYG is not working in iReport

Not Founded Style from Global Style Template
When a global style from a custom (self-created) style template is used

in a report, the style is not being recognized correctly after closing and
reopening the report, despite the fact that the same template is loaded
in iReport.
Effect The used style is being shown greyed out and with warning sign under
"Report styles"
• The style cannot be seen in the WYSIWYG designer.
When running the report, the style is being found and works.


Jasper Reports Working with Fonts
Introduction The default format for documents (reports) generated by APplus is PDF.
To obtain the desired output as PDF we need to understand how Jasper
Reports used the font properties and how the rendering engine of
Jasper uses the fonts.
This chapter also describes the encountered issues when generating
PDF documents and how they were solved.
Font Properties
Introduction A font is usually defined by the following basic characteristics:
• font family (Font Name),
• font dimension (Size) and
• attributes (Bold, Italics, Underline, Strikethrough, etc.).
Figure 10-1 Specifying the Font Properties
Technical Description JasperReports Jasper Reports Working with Fonts • 113

If a report is to be exported as a PDF file, JasperReports needs the

following additional information:
• PDF Font Name: The name of the font (it could be a predefined PDF
font or the name of a TrueType font (TTF) file present in the
classpath (see below).
• PDF Embedded: A flag that specifies whether an external TTF file

should be included in the PDF file.
• PDF Encoding: A string that specifies the name of the character

encoding.
If the report is not exported to the PDF format, the font used is the one
specified by Font Name and is enriched with the specified attributes. In
the case of a PDF document, PDF Font Name identifies the font used
and its attributes (bold, italics, etc.). For example
arialbd.ttf
defines the Arial font and bold attribute. Other attributes are ignored
since they are inherited from the specified PDF font.
Using Custom Fonts (TTF) in PDF Documents
Usage of external You can use external True Type font(s). To do so, the external fonts,
TrueType fonts these are files with .ttf extensions, must appear in the classpath. This is
necessary
• during design time (report editing or rendering in iReport) and
• in the run time (when the report is produced by the JasperServer).
Fonts inherited by the The Font name combo box in the Font tab of the element properties
operation system dialog, shows only the system fonts, managed by the Java Virtual
Machine (JVM).
These are usually inherited by the operating system. Therefore, to
select an external TTF font to use in non-PDF reports, you had to install
the font on your system before you can use the font.
The PDF font name combo box displays a list of PDF built-in fonts and
all TTF files found in the classpath on startup. These fonts are used
when the report is exported to PDF format. Therefore, to select an
external TTF font to use in PDF reports, we have to deploy it to
directory in classpath.
Notes • Scanning the whole classpath to look for TTF files is really
timeconsuming in terms of startup time. For these reasons, iReport
provides a possibility to limit the number of directories to scan
when looking for fonts.
To define the fonts path select in iReport Options > Fonts path and
check all the directories and JARs that must be scanned when
looking for fonts.
• To ensure that the external TTF font is viewed correctly in the

exported PDF, we have to select the PDF Embedded check box.
114 • Jasper Reports Working with Fonts Technical Description JasperReports

Creating PDF Document(s) Containing Unicode Text
Unicode Notes • Unicode fonts are typefaces containing a wide range of characters,
letters, digits, glyphs, symbols, ideograms, logograms, etc., which
are collectively mapped into the standard Universal Character Set.
• Unlike most conventional computer fonts, which are specific to a

particular language or legacy character set and contain only a small
subset of the UCS characters, these fonts attempt to include many
thousands of possible glyphs, so that they can be used as a single
typeface across multi-lingual documents.
• If a font is chosen which does not contain a glyph for a codepoint

used in the document, typically a question mark ("?"), a box, or
some other Substitute character is displayed.
• Even if font supports Unicode, it doesn't mean that all characters

are provided. For example, Arial font supports Latin, Greek, Cyrillic,
Hebrew and Arabic Unicode subrange, but it doesn't support
Chinese or Japanese characters.
Requirements • A font that supports Unicode (i.e. Arial).
• Font files must be deployed to iReport, JasperServer (and Print

Server) (to the folder that is in the application’s classpath).
• We don’t modify classpaths of iReport or JasperServer. Instead

we use the classes folder for all resources that are needed to
render a report and must be therefore in the classpath.
There is a difference in the JasperServer and the iReport

deployment:
• JasperServer - Fonts (e.g. arial.ttf, arialbd.ttf, ariali.ttf,

arialbi.ttf) and fontmap.xml are deployed into the classes
folder.
• iReport - Fonts (e.g. arial.ttf, arialbd.ttf, ariali.ttf, arialbi.ttf)

are deployed to the fonts subfolder (of iReport). The file
fontmap.xml must be deployed into the classes folder.
• The file fontmap.xml must be deployed to iReport, JasperServer

(and Print Server).
• The file fontmap.xml is needed when reports that contains

styled texts are exported to PDF. It contains a mapping
between Font Name plus formatting attributes (on one hand)
and the name of the font spezified in the field PDF Font Name
(on the other hand).
• The Font Path of iReport must point to a location where the fonts
were deployed.
• The Font Path is part of the configuration setting of iReport. It

defines the location where iReport searches for font files. The
font files that are found are displayed in the PDF Font Name list.
Since iReport automatically scans the fonts directory during
startup, no changes are necessary.

Font properties Font properties must be set as follows:
• Font Name must define a font with Unicode support.
• PDF Font Name defines the font file that will be used when the
report is exported to PDF.
• The PDF Embedded must be set to true!
• PDF Encoding must be set to Identity-H (Unicode with horizontal

writing)
Note: In the field PDF Font Name is a file selected that contains a font
with certain attribute applied. Example mappings:
PDF Font Name Font name Attribute
arial.ttf Arial font regular (no attributes

applied)
arialbd.ttf Arial font bold attribute set
ariali.ttf Arial font italics attribute set
arialbi.ttf Arial font bold and italics

attributes set
Hence, when we modify formatting attributes (in the font properties,

e.g. bold, italics, etc.) we also have to select the correct font file!
Using Unicode Font in In the standard implementation all Static Text elements and Text Field
The Style Template elements (in reports) has to use a style from the APplusStyles template.
The template uses Unicode font. The default style defines an Arial font
together with other mandatory properties for Unicode support:
• Font Name is set to Arial.
• PDF Font Name is set to arial.ttf.
• PDF Embedded is set to true
• PDF Encoding is set to Identity-H
All styles are derived from the default style. If a style uses formatting
attributes (Bold, Italics, Bold Italics) it updates the specified style in the
field PDF Font Name appropriately, i.e. when the Bold attribute is set in
the style, the specified font in the field PDF Font Name for the style is
changed to
arialbd.ttf
The same approach must be used also for other Unicode fonts that are
added to the style template.

Text formatting
Styles Used by Static Normally, all the text content in a text element has the style specified
Text and Text Field by the text element attributes (text foreground color, text background
color, font name, font size, etc.). But in some cases, we want to
highlight a few words inside a text element, e.g. changing the font color
or style (bold or italic) or layout the text (by using a list). In such cases
the text content of that particular text element will no longer be pure
text, but it will include formatting information in the text itself.
Static Text …
Figure 10-2 Pure Text
…is changed to
Figure 10-3 Text With Formatting Information
Result • bold
• italics
• underline
superscript
•
• subscript

Markup Attributes
The Markup attribute on the Font tab of the element properties dialog
provides support for RTF and HTML snippets inside of text elements.
Figure 10-4 Markup Attribute On the Font Tab
The APplus reports use markup attribute since 50F04. The attribute is
used when fields contain HTML formatted text. Some tables in APplus
have fields that contain HTML snippets (e.g. offer or order). The
snippets are created with the FCKeditor. The JasperReport engine
supports only a limited number of HTML tags:
• <B>, bold
• <I>, italics
• <U>, underline
• <SUP>, superscript
• <SUB>, subscript
• <STRIKE>, strikethrough
• <FONT face, size, color>Comic Sans MS</font>
• <LI>
• <BR>

Notes • The unsupported tags are ignored (filtered out) by the engine.
• The engine supports <B> and <I> tags, but not <STRONG> and
<EM>, which are generated by the FCKeditor.
• There is an issue with <LI> tag (for more details see section
"Markup <LI> issue" on p. 122)
filterHTML() scriptlet The filterHTML() scriptlet function has to be used to preprocess the
HTML snippets. The function
• replaces the tag <STRONG> with <B> and the tag <EM> with <I>.
• implements a workaround for <LI> issue.
If you want to use the function, you have to enter the following line in
the Text Field Expression:
new
com.apag.p2plus.p2reports.scriptlets.APScriptlets().filterHT
ML($F{ARTIKELTEXT})
where $F{ARTIKELTEXT} is the field containing the HTML snippet.

Is Styled Text Attribute (Deprecated)
The Is styled text attribute indicates, whether the text content of the
element is pure text or has embedded style information. All text
elements have this special flag.
Note: The Is styled text attribute is deprecated. It was in use in APplus

reports from 50F00 til 50F03.
In 50F04 it was substituted with the new markup attribute.
Figure 10-5 Usage Of the Is styled text Attribute

Limitations and Issues
PDF Export Issue
When the report contains HTML formatted text (uses MARKUP font
attribute) and is exported to PDF, the bold and italics attributes are not
applied to the text. This issue is present in iReport, on the
JaspserServer and the APplus web server.
To overcome the problem a PDF export extension was developed. You
can read more about the extension in chapter "Custom PDF exporter"
on p. 155.
Note: The extension solves the export problem in iReport and

JasperServer. The PDF preview issue of formatted texts on the web
server was addressed as a separate issue (see next section).
PDF Export of Styled Text Doesn't Work When Using Web Service
We use the "PDF export extension"’ to overcome the PDF export issue
(see below) of inline formatted texts (see section "Text formatting" on
p. 117). The solution works when reports are exported to PDF on
JasperServer and in iReport.
But it doesn't work, when reports are previewed from APplus. When
APplus sends a report Run request via web service where PDF is set as
export format the report is not exported correctly. Export to other
formats such as RTF, HTML, jrprint (and also to PDF that doesn't
contain formatted texts) works correctly.
The issue was fixed by JasperSoft. The fix was provided as a patch for
the JasperServer v3.1. The fix was deployed as part of the 50F04 fix
pack.

Markup <LI> issue
Problem with the FCKeditor is used to produce the HTML formatted texts. In the reports
<li> tag these texts are rendered with the Markup attribute set to HTML
(markup="HTML"). When the <LI > tag is present in the text, the
report rendering fails with the following exception:
Error filling print… Invalid substring range
java.lang.IllegalArgumentException: Invalid substring range
at java.text.AttributedString.addAttributes(Unknown Source)
at
net.sf.jasperreports.engine.util.JRStyledText.getAttributedString(JRStyledText.java:1
13)
at
net.sf.jasperreports.engine.util.JRStyledTextParser.write(JRStyledTextParser.java:223
)
at
net.sf.jasperreports.engine.util.JeditorPaneHtmlMarkupProcessor.convert(JeditorPaneHt
mlMarkupProcessor.java:157)
at
net.sf.jasperreports.engine.fill.JRFillTextElement.processMarkupText(JRFillTextElemen
t.java:1356)
at net.sf.jasperreports.engine.fill.JRFillStaticText.(JRFillStaticText.java:57)
at
net.sf.jasperreports.engine.fill.JRFillObjectFactory.visitStaticText(JRFillObjectFact
ory.java:658)
at net.sf.jasperreports.engine.base.JRBaseStaticText.visit(JRBaseStaticText.java:101)
at
net.sf.jasperreports.engine.JRAbstractObjectFactory.getVisitResult(JRAbstractObjectFa
ctory.java:91)
at net.sf.jasperreports.engine.fill.JRFillElementGroup.(JRFillElementGroup.java:86)
at
net.sf.jasperreports.engine.fill.JRFillElementContainer.(JRFillElementContainer.java:
91)
at net.sf.jasperreports.engine.fill.JRFillBand.(JRFillBand.java:87)
at
net.sf.jasperreports.engine.fill.JRFillObjectFactory.getBand(JRFillObjectFactory.java
:518)
at net.sf.jasperreports.engine.fill.JRBaseFiller.(JRBaseFiller.java:451)
at net.sf.jasperreports.engine.fill.JRVerticalFiller.(JRVerticalFiller.java:77)
at net.sf.jasperreports.engine.fill.JRVerticalFiller.(JRVerticalFiller.java:59)
at net.sf.jasperreports.engine.fill.JRFiller.createFiller(JRFiller.java:147)
at net.sf.jasperreports.engine.fill.JRFiller.fillReport(JRFiller.java:57)
at
net.sf.jasperreports.engine.JasperFillManager.fillReport(JasperFillManager.java:402)
at
net.sf.jasperreports.engine.JasperFillManager.fillReport(JasperFillManager.java:234)
at it.businesslogic.ireport.IreportCompiler.run(IreportCompiler.java:947)
at java.lang.Thread.run(Unknown Source)
Workaround JasperSoft is preparing the fix for the issue. Meanwhile we are using the
workaround proposed by Jasper support, adding after each
<LI> tag. The workaround is implemented in the filterHTML() scriptlet
function. :

APplus Print Service
Overview
Introduction The print server
• application is used to print documents rendered with JasperReports.
• is running as a windows service and provides the printing services

to the APplus application.
• pools the APplus web server for print jobs and process them.
When a new print job is created in APplus, the print server obtains that
job, contacts the JasperServer for rendering the report and prints the
rendered report on one of the configured printers.
Features The print server
• can be run as an application or as a service.
• supports multiple instances:
• one instance can process print jobs from one web server,
• one instance can process jobs from one or more environments,
• one instance can process jobs from one or more users,
• each instance can be mapped to different web server.
• supports logging.
• can use different sizes of paper, so that the size of the report forces
the size of the paper, so that you can print labels for example (since
50F07).
• shows available printers (since 50F08).
In the print dialog all printers are displayed, which are known by all
printer servers. This will be considered, whether a print server uses
only certain environments or certain users.
As soon as the print server runs, the print server submits to APplus
always the printers, which the print server knows, in the demand
for printing jobs to be performed by whatever printer. This infor-
mation is stored in the new table DRUCKER.
Technical Description JasperReports APplus Print Service • 123

When the client opens the print dialog, then APplus displays the
correct printer based on the configuration of the print server in the
system configuration. The printer default printer and e-mail
(documents deposited with the e-mail address) will always be
displayed.
When you restart the application server, the information in the table
DRUCKER is adjusted so that the information is to be deleted from
the print servers that are not configured in the system configu-
ration.
This has the consequenz that users can now print on their locally
attached printer via the print server. To do this, this printer must be
shared on the client and the share on the print server must be set
up.
Requirements The requirements of the print server are:
• Microsoft Windows XP (or later)
• Sun Java (JE or JDK)
• APplus
• JasperServer
• At least one printer must be installed on the machine where the

print server is running.
The print server is a java application. It has Windows dependency,

though. It has some Windows specific code. The print server can be
installed and can run as a Windows service. The second dependency is
the usage of the windows fonts. The fonts are needed to create PDF
reports. The print server uses the fonts from the folder
Windows/fonts
Arial fonts with Unicode support are required.
124 • APplus Print Service Technical Description JasperReports

Installation The print server is located in the SVN folder
Tools/APplusPrintService
Export the folder to any location on your local file system. The folder
will contain:
File Description
APplusPrintService.jar Print server application jar file
run_on_console.cmd Batch file to run the print server on the

console
install_service.cmd Batch file to install the print server as a

windows service
uninstall_service.cmd Batch file to uninstall the print server as a

windows service
conf Configuration files

• printserver.config.xml - print server
configuration file
• log4j.properties - logging configuration
• fontmap.xml - map between font name
and font files, used for creating PDF
lib All necessary libraries
fonts Contains locale specific and/or custom

fonts
Mandatory Configuration Settings
Before you can start using the print server, you have to perform the
configuration changes in the configuration files of the print server and
in the systemconfiguration of APplus.
Settings In the Configuration File Of the Print Server
1. Open the file printserver.config.xml in the editor.
2. Change the following line according to your system configuration:

<web_server url="http://localhost/APplusJasper/" name="PrintServerTest" />
where
• url is the base url to the web server and
• name is the instance name of the print server.
Note: Both attributes are mandatory. The print server supports

multiple instances. Each instance can serve a different web server. To
configure printing from more than one web server, simply add a new
configuration line. Be aware that the name of the print server instance
should be unique!

Settings In the Systemconfiguration
Basic Configuration All JasperReport print jobs will be served by the configured print server
instance.
1. Open the APplus Manager.
2. Select the company (Firma), for which you want to configure the print
server.
3. Open the module SysConf and navigate to Reporting / Print Server.
4. Enter in the field First Instance the instance name of the print server
you defined in the file printserver.config.xml (name attribute, see
below).
5. Leave all the other fields empty.
Extended
Configuration
1. Specify in the systemconfiguration in the section Reporting/Print Server

in the field Environment for the first instance the print server instance,
when you want that only print jobs from specified environment(s) are
printed on the selected print server instance.
It is possible to define multiple environments. The environment names

have to be separated with a semi colon ";".
Leave the field Environment for the first instance empty, when you
want that print jobs from all environments are printed on the selected
print server instance.
2. Define a user in the field User for the first instance when you want that
only print jobs created by specified user(s) are printed on the selected
print server instance.
It is possible to define multiple users. The names of the users have to

be separated with a semi colon ";".
Leave the field User for the first instance empty, when you want that
print jobs from all users are printed on the selected print server
instance.
3. The user names must be the APplus user names (p2user) (as defined in
PERSONAL table).
4. Be aware that environment and user definitions are joined together with
AND, when a job filter is created. So, if you specify an environment and
a user from a different environment, the print server will not get any
print job.
One web server can host multiple environments. It is possible to

configure a dedicated print server instance for each environment.
In order to map the print server instance to a specific environment, we
have to go to the settings to the print server in the system configu-
ration and enter the instance name (field Name of the first Instance)
and environment (field Environment for the first instance). At the
moment it is possible to configure up to four dedicated instances.

Start the Print Server
The print server can be run as an application or as a Windows service.

The starting and managing of the print server was improved and
simplified with the fix pack 50F07.
It was the opportunity created to start the APplusPrintService now by

double clicking and from the dialog to install or to remove the
APplusPrintService, to view the log file or to start the print server from
the console.
There it is now no longer required to run, to install or uninstall the
services with the help of the batch files
• install_service.cmd,
• uninstall_service.cmd and
• run_on_console.cmd.
Please note that after installing the APplusPrintService you still have to
configure and start the service with the relevant service user on the
services manager of the operating system.
Notes • The logging output must be set to FILE, when the print server is
running as a Windows service.
• Printers that use file drivers (such as PrimoPDF or Microsoft Office

Writer) will FAIL to print, when the print server is running as a
Windows service.
• When the print server is installed as a service and PrimoPDF or

MS Office Writer is used as a printer, the PrimoPDF (Office
Writer) driver can't display the Save dialog. This is because the
services by default can’t interact with the desktop. For local
services (but not for network services) it is possible to define
that they can interact with the desktop. See service properties
(Log On tab).
• java.exe needs to be in PATH to install or uninstall the service. The

service will run without java.exe in PATH.
• Use the batch file
uninstall_service.cmd
to uninstall the print server service.

Technical Description
Class Diagram and Technical details such as the class diagram and the sequence diagram
Sequence Diagram are described in the following passages.
The print server is running as a Windows service and provides printing

services to the APplus application. It pools the APplus web server for
print jobs and processes them. When a new print job is created in
APplus the print server obtains that job, contacts the JasperServer for
rendering the report and prints the rendered report on one of the
configured printers.
The class diagram of the print server application shows all classes that
are implemented in the print server and their relationships and usages.
For better understanding the remote external components are also on
the diagram and are drawn in green color (webserver, jasperreports)
and classes from other libraries are colored in blue (Properties,
TimerTask, Thread, Win32Service).
Figure 11-1 Class and Sequence Diagram
As it can be seen on the diagram the print server can also be run by a
user on the console.
Javadoc Developers, who are interested in the API, can generate the
Documentation documentation from source code comments by using javadoc.

Basic Printing Flow Basic printing flow is described in the chapter "JasperReports
Architecture" (for details see section "Print Operation" on p. 20).
Notes
The print server doesn't render reports. Reports are rendered by the
JasperServer.
The print server sends a rendering request to the JasperServer and as a

result gets the report in .jrprint format.
The print job consists of
• sending the report to the selected printer.
• exporting the report to PDF and sending the PDF to the web server
(to be stored in DMS).
In the systemconfiguration under reporting/general you can specify,

whether the checkbox print on documents will be immediately be
activated after pressing the button or after the document is been
printed. The default setting is immediately.
The file DocTypes.xml must contain the printer name as displayed in

the Windows Printer & Faxes settings.


Jasper Reports Conditional Column Hiding
Introduction Sometimes it is necessary to hide a column depending on a condition by

using an expression specified in the Print when expression on the tab
Common in the properties dialog of a report element.
Only when the condition of the expression is met, the report element
will be displayed. But the problem is that the blank space is left. The
space that is freed should be removed or reused by other elements in
the same row.
Altering Report Templates at Runtime
The columns have to be placed or moved in the template using the API
before running the report.
APCustomJSReportService
The service APCustomJSReportService implements the functionality of

conditional column hiding.
The report template is preprocessed on the fly before the data is filled
to the report and before the report is rendered. All the report bands and
their content are analyzed. For each report element the Print when
expression is evaluated. When the evaluation result is FALSE the
element is removed.
Note: Only parameters ($P{parameter_name}) are supported in

expressions. At the preprocessing time, the data from the data source
are not available and report fields and variables are uninitialized.
Hence, Print when expression (used for column hiding) can't contain
fields or variables.
removeColumns Only reports that have removeColumns parameter defined and properly
Parameter initialized are preprocessed. Two values can be defined for the
removeColumns parameter:
• remove - free space is removed and columns are shifted to recover

free space.
• redistribute - freed space is equally distributed between remaining

elements.
Report Processing Report processing is done in two steps. In the first step non visible
elements are removed and remaining elements are compacted. In the
second step the freed space is redistributed and is applied only if the
user selects to redistribute the freed space.
Technical Description JasperReports Jasper Reports Conditional Column Hiding • 131

JasperServer Integration
The standard class
com.jaspersoft.jasperserver.api.engine.jasperreports.service.impl.EngineServiceImpl
was extended. The fillReport method was overriden:
• The method retrieves the report template (JasperDesign object) and

the report parameter map.
• When the removeColumns parameter is defined and initialized
• the report is preprocessed (columns are removed and free

space is redistributed),
• the report template is recompiled and
• the standard reportFill() method is called.
• APCustomJSReportService.jar, is bundled inside

APJasperExtensions.jar that has to be deployed to the folder
jasperserver-pro/WEB-INF/lib
• The deployment is performed by the APplus Manager with the

command APplusManager > Reporting > Jasper Integration >
Jasper Server:
• Activate the checkbox JAR-Dateien kopieren.
iReport Integration
iReport (v.3.0.0) doesn't provide extension points. It does provide

extensions with the plugins. The conditional column hiding functionality
was implemented as an iReport plugin - APReportRunExtensionPlugin.
• The plugin extends the regular report execution (Run).
• A template preprocess step have been added to the standard report

execution steps (compile, fill, export).
• The report template is preprocessed only when the removeColumns

parameter is defined and properly initialized.
• The APReportRunExtensionPlugin is bundled in the plugin

APReportExtensionsPlugin that has to be deployed to the folder
iReport/lib
Notes • The plugin APReportRunExtensionPlugin uses the functionality from

the service APCustomJSReportService.
• The jar file APCustomJSReportService.jar is bundled in the jar file

APJasperExtensions jar.
• So the jar file APJasperExtensions.jar has to be deployed to iReport

and it has to be in the classpath for the plugin to work.
The deployment has to be performed with the APplus Manager with the
command APplusManager > Reporting > Jasper Integration > iReport:
• activate AP Plugin installieren (APReportExtensionsPlugin.jar).
• activate JAR-Dateien kopieren (APJasperExtensions.jar,

barcode4j.jar, jtds.jar).
132 • Jasper Reports Conditional Column Hiding Technical Description JasperReports

Report Template Requirements
To use the functionality of conditional column hiding, we need to design

the report templates correctly. The following requirements must be
met:
• the report design must have a tabular design.
• the report design must contain the removeColumns parameter:
• remove - free space is removed and columns are shifted to

recover free space.
• redistribute - freed space is equally distributed between

remaining elements.
• the "table" must be in the master report.
• The expression in the Print when expression used for column hiding
can contain only parameters (fields and variables are not
supported).
Limitations
• When the fields are not properly positioned, i.e. the fields couldn´t
be removed correctly if they don’t belong to the frame, and are
positioned between fields that belong to the frame columns.
• The report must have a tabular design.
• The number of columns must be equal in all rows in order for the
redistribution to work correctly. When this requirement is not
satisfied, the column alignment is wrong (lost).
• The "table" must be part of the master report.
Example
BestellungLang The example of statistical reports is bestellungLang.jrxml. It is located

in the folder.
../purchase/statistic
The report was created from the subreport bestellungLang-

Detail_sub.jrxml.
Figure 12-1 Report bestellungLang.jrxml

To satisfy the requirements of the report template the report structure

was modified:
• the master and the subreport were merged,
• the merged elements were split (tabular layout),
• the same expression in the field Print when expression was applied
on all elements forming a column,
• the removeColumns parameter was added (with the default value

set to remove) and
• frames were introduced for row representation.
All elements in a row are grouped inside a frame. A common styles

and expression are applied on the frame (instead of a single ele-
ment).
Figure 12-2 Grouping Of Elements In a Frame

Using Special Report Design
When the columns are removed, the empty row space is not recovered!
To resolve this issue we can resort to the following workaround:
1. For each column combination create a separate table header row, table
detail row and a table footer row.
2. Conditionally display the proper table header, table detail, table footer
row.
Note: The removeColumn parameter must not be defined!
Example The example for a statistical report is auftragLang.jrxml. It is located in

the folder
../sales/statistic
The report is created as the subreport auftragLangDetail_sub.jrxml.
The subreport contains three different column layouts.
Each layout displays different columns.
The space from hidden columns is redistributeable between visible

columns.
The column layout is realized with a row that is conditionally displayed.
Table Header
Figure 12-3 Table Header Row
Table Detail
Figure 12-4 Table Detail Rows


AP Query Executer (APQE)
Introduction Jasper Reports allows us to specify queries in languages other than

SQL.
Each query language is associated a query executer factory
implementation that creates the corresponding query executer. The
query language used by APplus reports is apqe.
The language is associated with the AP query executer factory
(APQueryExecuterFactory). The factory creates four different query
executers:
• (custom) SQL,
• Sel Info,
• Mandant,
• Web Service.
Query Executers Which of the query executer is selected based on the first word in the
query:
• SELECT - SQL Query Executer,
• SELINFO - Sel Info Query Executer,
• MANDANT - Mandant Query Executer,
• WEBSERVICE - Web Service Query Executer.
Tasks of apqe Besides the query execution apqe performs other tasks:
• it creates a connection to the DB server and maintains a pool of

opened connections,
• it creates proxies for web services and maintains a pool of created

proxies,
• it reads mandatory parameters (appserver, p2user) from

applus.config.xml (when they are not defined),
• it reads query snippets from SelParts.xml (statistical reports).
Technical Description JasperReports AP Query Executer (APQE) • 137

Execution Contexts apqe is bundled together with two other jar files to
APJasperExtensions.jar and deployed to iReport and the JasperServer.
apqe supports three execution contexts:
• APplus - the run request of the report is sent from APplus. The
request is processed by the JasperServer. apqe runs on the
JasperServer.
• iReport - the request of the report is created and processed by

iReport. apqe runs in iReport.
• JasperServer - the report request is created on the JasperServer

(web interface). The request is processed by the JasperServer. apqe
runs on the JasperServer.
Depending on the execution context are the parameters initialized

differently:
APplus iReport JasperServer
mandatory parameters provided by the read from read from

APplus web server applus.config.xml applus.config.xml
company read from the based on the report

iReport properties location in the re-
pository
selFields, selJoin provided by the read from read from

APplus web server SelParts_<company_ SelParts_<company_
name>.xml name>.xml
apqe has the following external dependencies:
• Sel_<company_name>.xml - when a statistical report (that uses

SelInfo) is executed,
• applus.config.xml - when a report is run in iReport or from the

JasperServer web interface,
• SelParts_<company_name>.xml - when a report is run in iReport

or from the JasperServer web interface.
138 • AP Query Executer (APQE) Technical Description JasperReports

AP SQL Query Executer
The APSqlQueryExecuter is used for all queries that start with the
SELECT keyword. The AP SQL Query Executer is a subclass of the
JRJdbcQueryExecuter
and the query execution flow is basically the same as if normal SQL
language would be used in the report.
The differences lay in the manipulation of the SQL query before the
query is executed on the SQL server.
Tasks Of the AP SQL The AP SQL query executer typically

Query Executer
• expands the table and field names to full names,
• adds the mandant specific fields to the query (selection, filtering),
• converts the where parameter to WHERE sentence in SQL syntax,
• adds or removes the ORDER BY sentence based on the orderby

parameter.
• implements Jahresvergleich processing (legacy).
Syntax SELECT <columns in SQL-Syntax >

FROM <table> [AS Alias] [<joins in SQL-Syntax>]
[WHERE [<search criteria in SQL-Syntax> AND] $P{where}]
[other SQL-statements]
[ORDER BY [<columns in SQL Syntax>,] [$P{orderby}]
Parameters • where - where parameter
• orderby - orderby parameter

Execution Sequence
Figure 13-1 Execution Sequence Of the AP SQL Query Executer

Sel Info Query Executer
Usage APSelinfoQueryExecuter is used for all queries that start with the
SELINFO keyword.
Tasks It is provided for
• retrieving and displaying the WHERE conditions of the report

defined in the where parameter.
• converting DB field names (used in the where parameter) to user

friendly names.
The language parameter is used for field translation and for locale
dependent data formatting.
Notes • The mapping betwen DB field names and user-friendly names is

defined in the file Sel.xml.
• The xmlnode parameter is used to locate the node in the file

Sel.xml that contains the proper mapping.
• The recordset returned by the query executer contains strings only.

The query executer converts and formats the data used in the
where parameter according to the type definition in the file Sel.xml.
Supported data types are:
• string,
• i2, integers, the used format depends on the localization
• number, floating numbers, the used format depends on the

localization
• date, date only, the used format depends on the localization
• datetime, date and time, formated to
YYYY-MM-DDThh:mm:ss
• time, duration, formated to
hh:mm:ss
• The file Sel.xml must be deployed to iReport and JasperServer for

apqe to use it
• done by the APplus Manager (APplus Manager > Reporting >

Jasper Integration > Selektions-XML vom AP Web Server
übernehmen)
• The multicompany support requires the file name in the format:
Sel_<company_name>.xml
• done by the APplus Manager (APplus Manager > Reporting >

Jasper Integration > Selektions-XML vom AP Web Server
übernehmen)
Syntax SELINFO $P{xmlnode} $P{where} $P{lang}
Parameters • xmlnode - the node from which the label is read (from the file
Sel.xml)
• where - where parameter
• lang - output language

Execution Sequence
Figure 13-2 Execution Sequence Of the Sel Info Query Executer

Mandant Query Executer
The APMandantQueryExecuter is used for all queries that start with the
MANDANT keyword. It is provided for obtaining current mandant based
on environment parameter given in report.
Syntax mandant
Parameters • N/A
Execution Sequence
Figure 13-3 Execution Sequence of the Mandant Query Executer

Web Service Query Executer
The APWebserviceQueryExecuter is used for all queries that start with

the WEBSERVICE keyword.
With this executer it is possible to invoke web services on the
application server that return a XML rowset as a result.
Syntax WEBSERVICE service name Type(value) Type(value) ...
Parameters • Service – full name of web service
• Name – name of the method
• Type – simple java type (String, Integer, Boolean, Double, Long)
• Value – the value of parameter
The parameters can be of mixed types and there can be optional

numbers of them.
Parameters can be
• hardcoded, e.g. "some text", 123, 1,234,
• report parameters, e.g. $P{param_name} and
• variables, e.g. $V{variable_name}
Function Parameter When parameters or variables are used as function parameters, they
are replaced with their values prior to the web service invocation!
Note: The $P{where} parameter is not converted to SQL syntax (as in

case of the SQL query executer).
The web service has to return some data in order for the field reader (in
iReport's query editor) to work and retrieve the fields.
Here is an example in an existing report: labinDifflisteDetail_sub.jrxml

WEBSERVICE p2automotive.LieferabrufIn getDiffListAsXml2
String($P{LIEFERABRUFIN}) String($P{DATETYPE})
Limitation The returned XML rowset is only partially converted to the DataSource.
The schema dtType attribute is just been ignored. The APWebservice-
QueryExecuter passes the name and the content of the field to the
DataSource. The data type is set to string regardless of the value of the
dtType attribute.

Other APQE components
Content In this passage other important apqe components and their

functionality are listed here.
APQueryExecuter- The tasks of the APQueryExecuterFactory is to

Factory
• manage and store the connections.
• substitute the Jasper connection with the APplus connection.
• create a user context for each report (master report, subreport).
• insert the mandatory parameters (appserver, p2user) to the report

parameter map when these parameters are missing.
• reads the selFields and selJoin parameters from the file

SelParts.xml, when multiple grouping is used in statistical reports.
APUserContext The APUserContext is a utility class for manipulating report parameter

map and storing user specific information (user name, application
server, environment, web server).
The user information is used to access web services and to obtain the
DB connection.
The context is instantiated
• by the apqe Factory and passed to the query executer, who is

responsible for the data collection.
• from the scriptlets that need web services.
Has the functions to read the mandatory parameters from the config file
and is aware of the selected company.
APQueryExecuter- The reader of the fields uses the apqe factory to instantiate proper
FieldsProvider apqe.
The APSqlQueryExecuter uses the same algorithm for query processing

as it is used during rendering.
Utility classes The classes P2WebUtils and P2QueryUtils were refactored in order to
support user specific web service consumption (application server,
p2user).
They use the factory of the web service to obtain SOAP stubs.
Static methods were removed.
The classes are instantiated by the query executer or scriptlets that

need their functionality.

APWebServiceFactory The APWebServiceFactory is used to create the web service proxies to

access the application server.
It requires information about application server, user name and web

service
The factory stores the proxy for reuse and the key is:
application server + user + web service
The factory is used by web utils and scriptlets that need web services.
Configuration and Other Files Used by apqe
apqe has the following external dependencies:
• Sel_<company_name>.xml - when a statistical report is executed

that uses SELINFO in the query.
• applus.config.xml - when a report is run in iReport or from

JasperServer web interface.
• SelParts_<company_name>.xml - when a report is run in iReport
or from the JasperServer web interface.
applus.config.xml
Usage The file applus.config.xml is used by apqe as a fallback when

mandatory parameters are not provided.
Usually it is used when a report is run in iReport or from the
JasperServer web interface.
<configuration>
<company name="Release5.0">
<parameter key="appserver" value="http://localhost:2042"/>
<parameter key="webserver"
value="http://localhost/Release5.0/"/>
<parameter key="p2user" value="bostjan"/>
<parameter key="env" value="prod"/>
<parameter key="localreportsfolder"
value="D:\APAG\Release5.0\Reports\Jasper\APplusJReports"/>
</company>
<company name="Trunk">
<parameter key="appserver" value="http://localhost:2040"/>
<parameter key="webserver" value="http://localhost/Trunk/"/>
<parameter key="p2user" value="bostjan"/>
<parameter key="env" value="ReferenzDB"/>
<parameter key="localreportsfolder"
value="C:\APAG\Reporting\Trunk\Reports\Jasper\APplusJReports
"/>
</company>
</configuration>

The file has to be customized (to contain valid parameter values):
• application server - APplus application server URL, e. g.
http://server:port
• webserver - APplus web server URL, e. g.
http://server/company_name
• p2user - APplus user name
• env - user's environment
Notes Each company is defined in a separate section.
The file and its content is managed by the APplus Manager.

How To ...
... Activate apqe Logging
JasperServer Add the following text to the file log4j.properties in the folder
C:\Program Files\jasperserver-pro-3.0\apache-tomcat\webapps\jasperserver-pro\WEB-
INF\log4j.properties:
### AP loggers
log4j.logger.com.apag=DEBUG
log4j.logger.com.apag.p2plus.p2reports=DEBUG
log4j.logger.net.sf.jasperreports.engine.query=DEBUG
The output is being written to i.e.
C:\Program Files\jasperserver-pro-3.0\apache-tomcat\webapps\jasperserver-pro\WEB-
INF\logs\jasperserver.log
iReport Create log4j.properties and add the following text to the file:
# Global logging configuration
# log file output

#log4j.rootLogger=ERROR, FILE
# console output
log4j.rootLogger=ERROR, CONSOLE
# Console output...
log4j.appender.CONSOLE=org.apache.log4j.ConsoleAppender
log4j.appender.CONSOLE.layout=org.apache.log4j.PatternLayout
log4j.appender.CONSOLE.layout.conversionPattern=%d{ABSOLUTE} %5p %c{1},%t:%L - %m%n
# Rolling log file output...

log4j.appender.FILE=org.apache.log4j.RollingFileAppender
log4j.appender.FILE.File=D:\\Java\\iReport-3.0.0\\iReport.log <----- modify this
line appropriately!
log4j.appender.FILE.MaxFileSize=1024KB
log4j.appender.FILE.MaxBackupIndex=1
log4j.appender.FILE.layout=org.apache.log4j.PatternLayout
log4j.appender.FILE.layout.conversionPattern=%d{ABSOLUTE} %5p %c{1},%t:%L - %m%n
### AP loggers
log4j.logger.com.apag=DEBUG
log4j.logger.com.apag.p2plus.p2reports=DEBUG
log4j.logger.net.sf.jasperreports.engine.query=DEBUG
Put the file in the folder
iReport/classes
The output is being written to i.e.
D:\Java\iReport-3.0.0\iReport.log

... Debug apqe
JasperServer To debug apqe, you have to run Tomcat in debug mode and then attach
to Tomcat.
Without Service
1. Add the following text
-Xdebug -
Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n
to JAVA_OPTS in:
\jasperserver-pro-3.0\apache-tomcat\bin\setenv.bat
2. Then restart JasperServer and attach in this example to port 8000.
With Service
1. Start the Tomcat Administrator Console
C:\Program Files\jasperserver-pro-3.0\apache-tomcat\bin\tomcat5w.exe
2. Add under
Java/Java Options
the following lines:

-Xdebug
-
Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n
3. Then restart the Tomcat service and attach the Tomcat service to port
8000 in this example.
iReport To debug apqe in iReport, you have to run iReport in debug mode and
then attach to iReport.
1. Modify the batch file
\bin\startup.bat
java -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=9998 -cp

"%IREPORT_CLASSPATH%" -Direport.home="%IREPORT_HOME%" -
Djava.security.policy="%IREPORT_HOME%/policy.all" -Xms128m -Xmx512m
it.businesslogic.ireport.gui.MainFrame %*
2. Set the classpath to
CLASSPATH=
3. Start iReport with
\iReport.bat
4. Attach iReport to port 9998 in this example.

... Jahresvergleich
Legacy Code
Note: The Jahresvergleich implementation in apqe is legacy code. The
implementation was ported from custom data provider for Reporting
Services.
This is report specific code and as such should not be implemented in

apqe. The code will be removed in the next time.
Current Solution To enable or trigger the Jahresvergleich processing by apqe we have to

define a Buchungsdatum input field in a *Sel.aspx page.
The input field has to be defined as:
<input id='BDATUM' name='BDATUM' dtType="date"

Field="_BDATUM">
Note: The Field attribute is used to trigger the special apqe

Jahresvergleich processing.
Preview Or Print When the report is previewed or printed:

Reports
• the user input for a statistical analysis is collected,
• a collection of key=value pairs is constructed,
• the collections is assigned to the where report parameter,
• the Buchungsdatum becomes part of the where parameter, e.g.
where=_BDATUM%3D[2004-01-01T00%253A00%253A00;2004-
12-31T23%253A59%253A59]
Example RechnungVergleichSel.aspx

*Sel.aspx Page The *Sel.aspx page contains the input field Buchungsdatum.
The input field is defined as:

<input id='BDATUM' name='BDATUM' dtType="date"
Field="_BDATUM">
Report The report contains a query with dummy sums.
The _BDATUM and _BDATUMX serve as a start or end marker for a SQL
snippet that has to be processed prior to the query execution, e.g.:
SELECT
VGL=t.artikel,
VGLNAME=vgl.name,
_BDATUM=" ,
ZEITRAUMUMSATZ=SUM(t.umsatz),
LFDGJUMSATZ=SUM(t.umsatz),
VORGJUMSATZ=SUM(t.umsatz),
VVORGJUMSATZ=SUM(t.umsatz),
LFDVJAHRUMSATZ=SUM(t.umsatz),
VJAHRVVJAHRUMSATZ=SUM(t.umsatz),
LFDGJDECKUNG=SUM(t.umsatz),
LFDGJMARGE=SUM(t.umsatz),
VORGJMARGE=SUM(t.umsatz),
ZEITRAUMMENGE=SUM(t.menge),
LFDGJMENGE=SUM(t.menge),
VORGJMENGE=SUM(t.menge),
VVORGJMENGE=SUM(t.menge),
_BDATUMX=" ,
GRUPPE=t.artikelgruppe,
GRUPPENAME=gj.name
FROM f_rechnung as t
left outer join artikelgruppe gj ON t.artikelgruppe =
gj.artikelgruppe
left outer join artikel vgl on t.artikel = vgl.artikel
WHERE $P{where}
GROUP BY t.artikel, vgl.name, t.artikelgruppe, gj.name

apqe apqe checks for the _BDATUM key in the where parameter.
When the _BDATUM key is defined, it performs the Jahresvergleich

processing (jahresvergleich()).
The fully processed query looks like this:

SELECT
VGL = t.artikel ,
VGLNAME = vgl.name ,
_BDATUM = N ,
_BDATUMX = N ,
ZEITRAUMUMSATZ = SUM ( CASE WHEN ( ( ( BUCHUNGSDATUM >= N'2004-01-01T00:00:00' AND
BUCHUNGSDATUM <= N'2004-12-31T23:59:59' ) ) ) THEN UMSATZ ELSE 0 END ) ,
LFDGJUMSATZ = SUM ( CASE WHEN ( ( ( BUCHUNGSDATUM >= N'20090101' AND BUCHUNGSDATUM <=
N'20091231 23:59:59' ) ) ) THEN UMSATZ ELSE 0 END ) ,
VORGJUMSATZ = SUM ( CASE WHEN ( ( ( BUCHUNGSDATUM >= N'20090101' AND BUCHUNGSDATUM <=
N'20091231 23:59:59' ) ) ) THEN UMSATZ ELSE 0 END ) ,
VVORGJUMSATZ = SUM ( CASE WHEN ( ( ( BUCHUNGSDATUM >= N'20090101' AND BUCHUNGSDATUM
<= N'20091231 23:59:59' ) ) ) THEN UMSATZ ELSE 0 END ) ,
ZEITRAUMMENGE = SUM ( CASE WHEN ( ( ( BUCHUNGSDATUM >= N'2004-01-01T00:00:00' AND
BUCHUNGSDATUM <= N'2004-12-31T23:59:59' ) ) ) THEN MENGE ELSE 0 END ) ,
LFDGJMENGE = SUM ( CASE WHEN ( ( ( BUCHUNGSDATUM >= N'20090101' AND BUCHUNGSDATUM <=
N'20091231 23:59:59' ) ) ) THEN MENGE ELSE 0 END ) ,
VORGJMENGE = SUM (CASE WHEN ( ( ( BUCHUNGSDATUM >= N'20090101' AND BUCHUNGSDATUM <=
VVORGJMENGE = SUM ( CASE WHEN ( ( ( BUCHUNGSDATUM >= N'20090101' AND BUCHUNGSDATUM <=
LFDGJDECKUNG = 0 ,
LFDGJMARGE = 0 ,
VORGJMARGE = 0 ,
LFDVJAHRUMSATZ = CONVERT ( DECIMAL ( 14 , 2 ) , CASE WHEN SUM ( CASE WHEN ( ( (
BUCHUNGSDATUM >= N'20090101' AND BUCHUNGSDATUM <= N'20091231 23:59:59' ) ) ) THEN
UMSATZ ELSE 0 END ) <> 0 THEN SUM ( CASE WHEN ( ( ( BUCHUNGSDATUM >= N'20090101' AND
BUCHUNGSDATUM <= N'20091231 23:59:59' ) ) ) THEN UMSATZ ELSE 0 END ) * 100 / SUM (
CASE WHEN ( ( ( BUCHUNGSDATUM >= N'20090101' AND BUCHUNGSDATUM <= N'20091231
23:59:59' ) ) ) THEN UMSATZ ELSE 0 END ) ELSE N'0' END ) ,
VJAHRVVJAHRUMSATZ = CONVERT ( DECIMAL ( 14 , 2 ) , CASE WHEN SUM ( CASE WHEN ( ( (
BUCHUNGSDATUM >= N'20090101' AND BUCHUNGSDATUM <=N'20091231 23:59:59' ) ) ) THEN
UMSATZ ELSE 0 END ) <> 0 THEN SUM ( CASE WHEN ( ( ( BUCHUNGSDATUM >= N'20090101' AND
BUCHUNGSDATUM <= N'20091231 23:59:59' ) ) ) THEN UMSATZ ELSE 0 END ) * 100 / SUM (
CASE WHEN ( ( ( BUCHUNGSDATUM >= N'20090101' AND BUCHUNGSDATUM <= N'20091231
23:59:59' ) ) ) THEN UMSATZ ELSE 0 END ) ELSE N'0' END ) ,
GRUPPE = t.artikelgruppe ,
GRUPPENAME = gj.name
FROM [virtualpc].[p2plusreferenz].dbo.f_rechnung AS t
LEFT OUTER JOIN [virtualpc].[p2plusreferenz].dbo.artikelgruppe gj ON (
t.artikelgruppe = gj.artikelgruppe ) AND ( gj.MANDANT = N'ZA' OR gj.MANDANT IS NULL
)
LEFT OUTER JOIN [virtualpc].[p2plusreferenz].dbo.artikel vgl ON ( t.artikel =
vgl.artikel ) AND ( vgl.MANDANT = N'ZA' OR vgl.MANDANT IS NULL )
WHERE
( ( ( ( BUCHUNGSDATUM >= N'2004-01-01T00%3A00%3A00' AND BUCHUNGSDATUM <= N'2004-12-
31T23%3A59%3A59' ) ) OR
( ( BUCHUNGSDATUM >= N'20090101' AND BUCHUNGSDATUM <= N'20091231 23:59:59' ) ) ) AND
( ( t.ART IN ( N'R' , N'G' ) ) ) AND ( ( t.STATUS <= N'4' ) ) AND
( ( t.POSITIONSART IN ( N'0' , N'1') ) ) ) AND ( t.MANDANT = N'ZA' OR t.MANDANT IS
NULL )
GROUP BY t.artikel , vgl.name , t.artikelgruppe , gj.name

... (Manually) Register apqe
Note: The apqe registration should be performed with the APplus

Manager.
JasperServer APplus Manager > Reporting > Jasper Integration > Jasper Server and
set the following checkboxes:
• AP Query Executor und Exportoptionen aktivieren

(jasperreports.properties),
• AP Erweiterungen aktivieren (applicationContext.xml).
Manual Steps
1. Edit the file jasperreports.properties.
<JasperServer install path>\jasperserver-3.0\apache-tomcat\webapps\jasperserver\WEB-INF\

classes\jasperreports.properties
2. Add the following lines to jasperreports.properties
• for the apqe registration:

net.sf.jasperreports.query.executer.factory.apqe=com.apag.p2plus.p2reports.apqe.APQue
ryExecuterFactory
• for the export options for excel files:
net.sf.jasperreports.export.xls.detect.cell.type=true
3. Edit the file applicationContext.xml.
<JasperServer install path>\jasperserver-3.0\apache-tomcat\webapps\jasperserver\WEB-INF\

applicationContext.xml
4. Add the apqe language to the supportedQueryLanguages property.
The edited section should look like this (notice apqe language):
<entry
key="com.jaspersoft.jasperserver.api.metadata.jasperreports.
domain.JdbcReportDataSource">
<bean
class="com.jaspersoft.jasperserver.api.engine.jasperreports.
util.DataSourceServiceDefinition">
<property name="serviceBeanName"
value="jdbcDataSourceServiceFactory"/>
<property name="supportedQueryLanguages">
<set>
<value>sql</value>
<value>SQL</value>
<value>apqe</value>
<value>APQE</value>
</set>
</property>
</bean>
</entry>

iReport APplus Manager > Reporting > Jasper Integration > iReport and set the
checkbox
• AP Query Executor und Exportoptionen aktivieren.
Manual Steps
1. Edit the file jasperreports.properties.
<iReport install path>\iReport\classes\jasperreports.properties
2. Add the following lines to jasperreports.properties.
• for the apqe registration:

net.sf.jasperreports.query.executer.factory.apqe=com.apag.p2plus.p2reports.apqe.APQue
ryExecuterFactory
• for the export options for excel files
net.sf.jasperreports.export.xls.detect.cell.type=true
3. Register the AP Query Executor in iReport with the command iReport >
Options > Query executors > New.
4. Insert in the dialog the following value:
Field Value
Language apqe
Factory Class com.apag.p2plus.p2reports.apqe.APQueryExecuterFactory
Fields Provider class com.apag.p2plus.p2reports.apqe.APQueryExecuterFieldsProvider

Custom PDF exporter
Overview
In cases when the value of a displayed text field containing HTML tags
(specifically <B> and <I>), the text in the PDF output is not styled as
to be expected. The bold and italic tags are ignored. In order to fix this
problem, a font map needs to be set as a parameter for the PDF
Exporter.
The reason of this problem is that in PDF bold and italic assigned text
must use a different font (derived from the base font). The PDF
Exporter needs to find at run time the font mappings.
JasperServer Solution
APCustomJSReportService implements a custom PDF Exporter that sets

the necessary font mappings before invoking a standard export method
on the JasperServer.
The custom class extends the class
com.jaspersoft.jasperserver.api.engine.jasperreports.service.impl.EngineServiceImpl
and overrides the exportToPdf() method.
The class needs to be registered on the JasperServer in order to use it

instead of the default one:
• The configuration of the engineService bean in the file
jasperserver-pro/WEB-INF/applicationContext.xml
has to be modified as follows:
Technical Description JasperReports Custom PDF exporter • 155

<bean id="engineService" class="com.apag.p2plus.p2reports.CustomReportService"

destroy-method="release">
<property name="repositoryService">
<ref bean="repositoryService"/>
</property>
<property name="dataSourceServiceFactories">
<ref bean="dataSourceServiceFactories"/>
</property>
<property name="compiledReportsCache">
<ref bean="hibernateRepositoryCache"/>
</property>
<property name="securityContextProvider" ref="securityContextProvider"/>
<property name="loggedInUserReportParameterName" value="LoggedInUser"/>
<property name="pdfFontMapLocation">
<value>/WEB-INF/classes/</value>
</property>
<property name="pdfFontMapName">
<value>fontmap.xml</value>
</property>
</bean>
• The file fontmap.xml contains the default mappings that can be
extended, if needed. The file has to be deployed to the folder:
<fontMap>
<fontKey pdfName="Arial" isBold="false" isItalic="false" >
<pdfFont pdfFontName="arial.ttf" pdfEncoding="Identity-H" isPdfEmbedded="true" />
</fontKey>
<fontKey pdfName="Arial" isBold="true" isItalic="false" >
<pdfFont pdfFontName="arialbd.ttf" pdfEncoding="Identity-H" isPdfEmbedded="true" />
</fontKey>
<fontKey pdfName="Arial" isBold="false" isItalic="true" >
<pdfFont pdfFontName="ariali.ttf" pdfEncoding="Identity-H" isPdfEmbedded="true" />
</fontKey>
<fontKey pdfName="Arial" isBold="true" isItalic="true" >
<pdfFont pdfFontName="arialbi.ttf" pdfEncoding="Identity-H" isPdfEmbedded="true" />
</fontKey>
<fontKey pdfName="Arial Black" isBold="false" isItalic="false" >
<pdfFont pdfFontName="ariblk.ttf" pdfEncoding="Identity-H" isPdfEmbedded="true" />
</fontKey>
</fontMap>
• APCustomJSReportService.jar, is bundled inside
APJasperExtensions.jar that has to be deployed to the folder
../jasperserver-pro/WEB-INF/lib
• The deployment and integration is performed by the APplus

Manager with the command APplus Manager > Reporting > Jasper
Integration > JasperServer and then activate the checkboxes
• JAR-Dateien kopieren,
• PDF Font Map und Arial-Fonts kopieren.
156 • Custom PDF exporter Technical Description JasperReports

Notes • It is possible to specify the name of the file containing the PDF font
map. See the properties of pdfFontMapName above.
• At the moment the property of pdfFontMapLocation is ignored. See

section "Limitation" of this chapter.
• The font is referenced in the default map (fontmap.xml). If the font,

which is used in the report, but not found on the server, the report
fails to render!
iReport Solution
iReport (v.3.0.0) doesn't provide extension points at the moment.

It does provide extensions with the plugins. The PDF export of HTML
texts functionality was implemented as an iReport plugin -
APReportRunExtensionPlugin.
• The plugin extends the regular report execution (Run).
• A preprocess and customized PDF export steps have been added to

the standard report execution steps (compile, fill, export).
• The export is customized only when PDF as an output format is

selected.
• The plugin APReportRunExtensionPlugin is bundled in the plugin

APReportExtensionsPlugin that has to be deployed to the folder
iReport/lib
• The file fontmap.xml has to be deployed to the folder
iReport/classes
Notes • The plugin APReportRunExtensionPlugin uses functionality from

• The jar file APCustomJSReportService.jar is bundled in the jar-File

APJasperExtensions jar.
• So the jar file APJasperExtensions.jar has to be deployed to iReport

and it has to be in the classpath for plugins to work.
The deployment and integration has to be performed with the APplus

Manager with the command APplus Manager > Reporting > Jasper
Integration > iReport and then activate the following checkboxes
• JAR-Dateien kopieren,
• AP Plugin installieren (APReportExtensionsPlugin.jar) and
• PDF Font Map und Arial-Fonts kopieren.
Technical Description JasperReports Custom PDF exporter • 157

Limitations
In the current state of the art:
• It is possible to use only one font map for all deployments.
• The location of the file fontmap.xml is predefined.
The font map file has to be located in the classes folder (on the
JasperServer).
158 • Custom PDF exporter Technical Description JasperReports

Security
APplus and the JasperServer support both the functionality of the user
authorization. The user's permissions are verified when the report is
being executed. By default can everyone render all reports. When we
need to configure the report execution, we use the plugin AccessRight
of the APplus Manager.
When we need to verify the user's rights of report execution on the

JasperServer, we have to install and configure the authentication filter.
The filter uses the APplus Security Manager to obtain and verify the
user rights.
APplus Access Rights
In APplus the permission checks of the report execution are

implemented in two places:
• On Rec pages based the generated print and preview menus on the
user´s permission of the current report. If the user doesn't have the
permission for a particular report, the print and preview menus
doesn't contain an entry for the report.
• When the link to the report is executed (loaded in browser) the

permissions are checked. If a particular user has the permission to
see the report (which will be generated based on the link), the
report will be rendered. If the permission check fails, the access will
be denied.
Checked Permissions Checked permissions are:
• if the user has a read access to the corresponding table.
• if the user has access to the report.
CheckOperation(report.module.documents.report_name |
report.module.statistics.report_name)
• if the user can use the environment for the report.
Missing Functionality • On Sel pages the grouping option by mandant should be shown
only, if the user has the permissions for all clients.
• The generated entries in print and preview menus on Sel pages

should be based on permissions.
Technical Description JasperReports Security • 159

Report Permission Configuration
Setup Of Report The setup of the Report permission is described in the chapter "Jasper
Permission Report Permission Setup" on p. 165.
Configuration
1. Open in the APplus Manager the plugin Zugriffsrechte and open the tab
Autorisierung.
2. You can add a new operation for a particular report with Definitionen >
Operationen and then press the right mouse button and then select the
option Anlegen.
The APplus Manager opens the dialog Name und Beschreibung.
3. For the report angebotAngebot write in the field Name the following:
report.sales.documents.angebotAngebot
4. This step is optional. To add a new role in the APplus Manager open
Definitionen > Rollen and then press the right mouse button and select
the option Anlegen.
APplus Manager opens the dialog Name und Beschreibung.
You can define a new role for example for
Report execution
5. To add permissions to the newly created role you can open the folders
Definitionen > Rollen-Aufgaben-Operationen and then mark one of the
listed users. Next press the right mouse button and select the option
Zuordnung ändern. Open the tab Operationen.
6. In our example select the following operation name:
To add a new role to the role assignment use Rollen-Zuweisungen and

then press the right mouse button and select the option Anlegen, i.e.
select role name: Report execution
7. To add a user to a role open Rollen-Zuweisungen, mark a role name

and then press the right mouse button and select the option Benutzer-
Zuordnung ändern and select a user name, i.e. your account name.
8. To save your changes, press in the APplus Manager the Speichern

button.
160 • Security Technical Description JasperReports

Verification With the following steps you verify that the access of printing a
proposal will be denied.
1. Open APplus and check that you can load a proposal (Angebot).
2. Verify that you can print and preview a report.
3. To remove the report execution permission open Definitionen > Rollen-

Aufgaben-Operationen and mark a role name. Then press the right
mouse button and select the option Zuordnung ändern. Open the tab
Operationen.
4. Deselect a operation name, i.e.
5. To save your changes press the button Speichern.
To check the content of the print or preview menu, you must open
APplus and load a proposal.
On the print and preview menu shouldn't be an entry for printing and
previewing the Jasper report for the document.
6. Check now the link invocation. Check that the link that was generated
by printing the document in step 5 can't be viewed.
7. Open the jobs and click on the link of the printed document.
The access should be denied.
JasperServer Access Rights
The report execution or the rendering permissions are being verified on

the JasperServer as well. The user can execute reports on the
JasperServer web interface only if the user has the appropriate
permissions. The JasperServer connects to the APplus Security Manager
to verify the user's permissions.
A custom security filter was developed to add this functionality to the

JasperServer.
Features
APplusAuthFilter provides the following functionality:
• Identification of the user with the help of the NT LAN Manager

(NTLM). NTLM is used only for the identification and not for the
authentication of the user.
• The permission for access of the JasperServer repository is checked

after the identification of the user and is performed on the security
manager.
• Prior to the report execution is for a particular report the permission

on the security manager checked.
• Single sign on is supported.

Install To enable the permission checking of APplus we have to install

APplusAuthFilter to APplusAuthFilter to the JasperServer.
JasperServer The filter is bundled into the APJasperExtensions jar file that has to be
deployed to the JasperServer.
1. The configuration file (on the JasperServer) applicationContext-

security.xml has to be modified as follows:
• Add a filter reference (CustomAuthenticationFilter) to the filter

chain.
<bean id="filterChainProxy" class="org.acegisecurity.util.FilterChainProxy">
<property name="filterInvocationDefinitionSource">
<value>
/**=httpSessionContextIntegrationFilter,userPreferencesFilter,
CustomAuthenticationFilter,AuthenticationProcessingFilter,userPreferencesFilter,
basicProcessingFilter,JIAuthenticationSynchronizer,
anonymousProcessingFilter,exceptionTranslationFilter,
filterInvocationInterceptor,switchUserProcessingFilter
</value>
</property>
</bean>
• Add a CustomAuthenticationFilter bean definition.
<bean id="CustomAuthenticationFilter"
class="com.apag.p2plus.p2reports.AuthenticationFilter">
<property name="externalUserService">
<ref bean="userAuthorityService"/>
</property>
</bean>
2. The Deployment of APJasperExtensions and the modification of the
configuration files have to be performed with the APplus Manager.
• In the APplus Manager open the plugin Reporting and then open the
tab Jasper Integration in the section JasperServer and activate the
checkboxes:
• JAR-Dateien kopieren and
• APplus Berechtigungsfilter aktivieren.
Attention ! This filter runs only if the Tomcat server runs with JDK 1.6 or higher!
To run Tomcat bundled with JasperServer under different JDK. The file
setenv.bat
should be edited. The file is located under
..\jasperserver\apache-tomcat\bin
In file setenv.bat set the JAVA_HOME variable to JDK 1.6 is installed on

the system. It will not run under the Java Runtime Environment (JRE).
If Tomcat is being run as a Service, reinstall the Service with
JAVA_HOME pointing to JDK 1.6.

How It Works
When we log in to the JasperServer for the first time, we are presented
with the authentication box. It is not the basic authentication dialog,
but NTLM authentication.
During the first login a so called shadow account is created on the
JasperServer. The shadow account gets assigned the JasperServer role:
ROLE_USER
That means that we are able to browse through the repository.
When we try to run the report, the CustomAuthenticationFilter kicks in

and verifies the user's permissions to run report. The
CustomAuthenticationFilter obtains the user's permissions from the
APplus Security Manager. If we have the permission, the report is
executed, if we don't have, we get a notification that we don't have the
permission to run the report.
After we successfully logged in JasperServer once, we don't need to

enter our credentials again. Next time we access to the server we get
straight into the welcome page (and not to the JasperServer Login
Page). To get to the JasperServer Login Page you have to log out first.
You are then in the JasperServer Login Page and can log in as one of
the users defined in JasperServer (jasperadmin, joeuser).
Note: We can't use our windows account to login via the login page of
Jasper. The shadow account created on the JasperServer is marked as
extern and the JasperServer doesn’t consider this account as one of its
own.
You can find detailed information in the documentation of JasperSoft in

the document
JasperServer Ultimate Guide
in the chapters
4.2 Acegi Security System for Spring
and
4.2.2 Acegi Filter Chain


Jasper Report Permission Setup
Introduction
Content The user's permissions are verified when the report is being executed.
By default can everyone render all reports. When we need to control
the report execution, we use the AccessRight plugin of the APplus
Manager. The topic describes how the report permissions are set up and
configured.
Set Up the Permissions
Overview We use here the report execution of proposals as an example
../sales/angebotRec.aspx
In the following example we will create a new group with one user and
then switch the access to the report in the APplus manager.
Here you find an overview of the necessary steps. You had to add
1. a new role.
2. the permissions to the new created role.
3. new operations for particular reports.
4. a role to the role assignment.

5. a user to the role.
Add a New Role First you add a new role. Open in the APplus manager the plugin
Zugriffsrechte and then open the tab Autorisierung.
1. Open the folder Definitionen and mark Rollen - Aufgaben - Operationen

and then press the right mouse button and select the option Anlegen.
2. Enter a Name, i.e.
Report execution
3. Enter a description for new role, i.e.
Test role, permission set up for report rendering
Technical Description JasperReports Jasper Report Permission Setup • 165

Add Permissions to
the Newly Created
Role
1. Mark the newly created role and then press the right mouse button and
select the option Zuordnung ändern.
2. Open the tab Aufgaben and press the button Alle.
3. Open the tab Operationen and press the button Alle.
Add a New Operation To add a new operation for a particular report you open in the APplus
For a Particular Manager the plugin Zugriffsrechte and the tab Autorisierung.
Report
1. Open the folder Definitionen and mark the folder Operationen and then
select the option Anlegen.
2. Add a new operation for a particular report, i.e.
166 • Jasper Report Permission Setup Technical Description JasperReports

Ad Hoc Reporting
Overview Jasper Ad Hoc Reporting is not part of the integration of Jasper Reports
in APplus. Jasper Ad Hoc Reporting is a feature from the JasperServer
that can also be used by APplus users. The user has to log in to the
JasperServer, where the user uses the Ad Hoc Editor to quickly create
reports he needs. The Ad Hoc Reports are based on Topics and
Domains, which has to be created and deployed to the JasperServer
prior to use of the Ad Hoc Editor.
The Ad Hoc Editor and the Ad Hoc Report management are described in
the JasperSoft documentation of the JasperServer
JasperServer Professional User Guide
in chapter
4 Working With Ad Hoc Reports
This chapter, on the other hand,
• presents experiences gained during the evaluation of the Jasper Ad

Hoc functionality and
• lists the limitations of the current solution.
About …
… Ad Hoc Reporting
Ad Hoc Reporting Ad Hoc Reporting refers to a type of reporting application that allows
business users to produce their own reports with little technical
knowledge. They must neither be programmers, nor designers. They
don´t need any SQL knowledge and most importantly they must not
wait to get the report.
Ad Hoc Reporting tool Typically an Ad-hoc Reporting tool presents a view of the database's
structure and the user visually drags and drops the fields from the
structure onto the report - specifying any filtering, grouping or sorting
they wish to apply.
The report is then saved and can be pulled up and executed at any time
the user wishes: The report is under total control of the user.
Technical Description JasperReports Ad Hoc Reporting • 167

Ad Hoc Editor Part of the JasperServer Pro distribution is also the Ad Hoc Editor. The
Ad Hoc Editor allows end-users to create and refine reports on-the-fly.
We can drag and drop columns and groups, select labels and styles,
select summaries and data formats for each column. The Ad Hoc Editor
is web based and is part of the JasperServer web interface.
… Topics and Domains
Ad Hoc reports are created from Topics and Domains defined by a user
with administrative permissions.
• The Topics, that form the basis of Ad Hoc reports, can be created in
iReport. Topics are usually created as JRXML files. These JRXML files
can only include a query and its parameters; all other report ele-
ments are ignored. Topics must be uploaded to the proper location
in the repository. When an end user clicks Create > Ad Hoc Report
on the Home page of the JasperServer, the list of Topics that
appears on the Topics and Domains page is populated from that
location. Once we have defined and published a Topic, we can use it
to create Ad Hoc reports.
• A Domain is an artificial data source created from one or more

actual data sources in your JasperServer database. Domains are
used in the Ad Hoc Editor to generate reports just as Topics are
used. They are different from topics in that they are much more
flexible. A Domain can filter the data from your actual data sources
so that you see only the data that you need for the current report,
ignoring other data in the data source that you don’t need. A
Domain can combine data that couldn’t be combined ordinarily, and
can use it differently, more meaningful names for the report’s
columns and rows to help users to understand the data.
If you installed the sample data, your repository includes Topics and
Domains you can use to explore the Ad Hoc Editor. For more
information about Topics and Domains, see the Documentation of
Jaspersoft
168 • Ad Hoc Reporting Technical Description JasperReports

Working With Ad Hoc Reports
Topic Creation The Topics are usually created by the persons who are familiar with the
data and database schema.
• The simplest way to create Topics is to create new JRXML files using
iReport, then use the iReport plugin of the JasperServer to upload
them to the repository.
• Jaspersoft recommends that a Topic’s JRXML file should not include

anything other than the query and the field list.
An example topic was created during the AdHoc evaluation. An

example topic is available on the website of the AP online support
http://www.applus-online.com/Support/Tools/Tools.asp
The evaluation investigated the
• possibility to create reports that are in the design and functionality

similar to current statistical reports.
• possibility of storing Ad Hoc reports in the JasperServer repository

and rendering them on demand (via web interface or web service).
• ability to edit and change stored reports.
The topic is based on the statistical reports of orders. It contains a

“universal query” that allows the grouping of data based on different
criteria. The analysis type (Lang) is predefined (fixed). With this topic it
is possible to create all Lang and Kurz statistical reports. For each
grouping a new report can be created.
Report Authoring Once the Topic is deployed it can be used as a starting point for report
designs.
The design process is straight forward, we just drag and drop fields that
must be displayed, select the fields that are used for grouping and
define summary (summing). The formatting is more or less predefined,
but it is possible to edit the labels and to use predefined styles. If
additional design changes are required, they have to be done in iReport
(after the report is saved).
For more information about designing an Ad Hoc Report, see the

documentation of Jaspersoft
Take a look in the chapter
4.2 Designing an Ad Hoc Report
There you will find the information about three supported report types
(Table, Chart and Crosstab) and a step by step example describing the
creation of a Table Report. The chapter has these sections:
• Table, Chart, and Crosstab Reports
• Selecting the Contents of a Table Report
• Formatting the Appearance of a Table Report
• Adding a Chart to a Table Report

Report Storing After the end of the design phase of the report, the report can be stored
in the JasperServer repository. We can freely select an appropriate
location in the repository and define a suitable report name. The Report
is stored as a report unit that contains only a master report. Once the
report is saved, it is possible to run it from the JasperServer web
interface or via web service request (i.e. from iReport, with the
JasperServer plugin of iReport).
Report Editing Stored reports can be opened and edited in the Ad Hoc Editor and in
iReport. When iReport is used for editing, one has to be aware of the
following:
• Reports are corrupted when
• the data grouping is changed and
• the field list is changed.
• Supported modifications are
• changing visual elements, such as changing the color scheme,
• adding images,
• changing fonts,
• moving elements.
• Changes made in iReport appear when the report is run, but if the
report is opened in the Ad Hoc Editor, they are not visible.
• Changes made in iReport are lost, when the report is opened in the
Ad Hoc Editor and then saved.
Notes
• When we run an Ad Hoc report, the entire result set is loaded into
the memory cache. We must take care that each Topic’s query
returns a manageable amount of data, depending on the
environment’s load capacity.
• iReport can edit Ad Hoc reports, but the groups and sorting you
defined in an Ad Hoc report will be lost.
• If we need to change the query (i.e. addition of a new field, join of

a new table), we need to create a new Topic and recreate all
reports. It is not possible to change the data set (field list) in the Ad
Hoc Editor (and it is forbidden to do this in iReport).
• apqe is used as a query executer. This means that APplus special

parameters ($P{WHERE}, $P{ORDERBY}) can be used in Topic
queries and consequently in all reports that are based on such a
Topic.
• Global Style templates are not supported in Ad Hoc reports (and

Topics). Styles are defined as local report styles. That means that, if
we want to change the style, we have to open or edit each report.

Limitations
• Topics can be deployed only to the predefined folder.
• Multiple companies are not supported. If topics from more than one
company are present in the adhoc folder, all companies will use the
same DB-connection settings. The issue is present during design
phase.
• Access permissions are not verified on APplus. Access permissions

can be defined only locally on JapserServer.
Quick How To
• create a topic
• deploy a topic
• On the JasperServer create a folder
company_name
in the folder
/adhoc/topics
The folder name must be equal to the company name for which
we create Ad Hoc reports (same as it is in reports folder).
• deploy the topic to the folder as described in the documentation

of Jaspersoft
JasperServer Professional User Guide,

chapter 4.1 Uploading a Topic
• create an Ad Hoc report see
JasperServer Professional User Guide,

Chapter 4.2 Designing an Ad Hoc Report.
• store an Ad Hoc report
• reports must be stored in the folder
/reports/company_name/adhoc


Jasper Reports How To
This is a collection of How to for Jasper reporting.
How to Use Alias in SQL JOIN Sentence?
Why to Use Aliases? Sometimes we need to use an alias for a DB field in the SQL SELECT
statement. The reasons could be:
• an operation is performed on the field (prior to assign the value),
• a field is the result of a subselect query or UDF function,

• the name of the alias is more descriptive than the field name of the
table.
Problem • aliases can not be used in JOIN and WHERE statements.
Solution • derived tables
Example Address subreport
• JasperReports doesn’t support multiple datasets in a single report.
• We need to get as many data as possible with a single SQL query.
In the Address subreport we need a data from three different tables:
• ADRESSE,
• URSPRUNGSLAND and
• "SYSCONF" (systemconfiguration).
We join the first two tables (ADRESSE, URSPRUNGSLAND) and use

subselect to get the data from the third (SYSCONF).
SELECT
FIRMANAME=adresse.firma1,
ADRESSNAME=adresse.name,
STRASSE=adresse.strasse,
STRASSE1=adresse.strasse1,
PLZ=adresse.plz,
ORT=adresse.ort,
LANDNAME = isnull(ursprungsland.name, ),
LAND = isnull(ursprungsland.land, ),
MYLAND = (select MYLAND=##Sysconf('stamm', 'myland'))
FROM adresse
LEFT JOIN ursprungsland ON ursprungsland.land = adresse.land
WHERE adresse=$P{DocNrAddress}
However, what we need is the field SPRACHE from the table
URSPRUNGSLAND that depends on the data returned by the subselect
query (MYLAND).
Technical Description JasperReports Jasper Reports How To • 173

By using derived tables we can enhance the initial statement and get
the information we needed:
SELECT
DERIVED.*,
ULSPRACHE = ursprungsland.sprache
FROM (
SELECT
FIRMANAME=adresse.firma1,
ADRESSNAME=adresse.name,
STRASSE=adresse.strasse,
STRASSE1=adresse.strasse1,
PLZ=adresse.plz,
ORT=adresse.ort,
LANDNAME = isnull(ursprungsland.name, ),
LAND = isnull(ursprungsland.land, ),
MYLAND = (select MYLAND=##Sysconf('stamm', 'myland'))
FROM adresse
LEFT JOIN ursprungsland ON ursprungsland.land = adresse.land
WHERE adresse=$P{DocNrAddress} ) AS DERIVED
LEFT OUTER JOIN ursprungsland on ursprungsland.land =
DERIVED.MYLAND
Note how the initial SQL query is "wrapped" into another query, so that
the alias(es) from the inner query can be used in the outer query.
How to Create a Search Criteria with a Field That Is Not

Part of the Table?
Problem • Sel page creates the search criteria with the field that is not present
in the table.
• the field is used in a JOIN statement
Solution • derived tables
Example The report wauftragWAuftragLANG_sub is a subreport of a statistical

report.
• The report is invoked from the *Sel.aspx page
wp/wauftragposSel.aspx
• The Sel page creates the search criteria with the field WAUFTRAG
e.g.,
WAUFTRAG=[10;10]
that is not present in the table WAUFTRAGPOS.
• The field WAUFTRAG is the field POSITION in the table

WAUFTRAGPOS.
174 • Jasper Reports How To Technical Description JasperReports

• The field naming issue is the result of supporting backward

compatibility.
• The Reporting Services reports use a view f_wauftragpos that

changes the name of the field from POSITION to WAUFTRAG.
• That is the reason, why the Sel page creates the search criteria
with the field WAUFTRAG.
• The jasper version of the report doesn’t use the view, but
performs the query on the table WAUFTRAGPOS directly.
• The field POSITION is aliased to WAUFTRAG, but this causes a

run-time error (due to the alias usage in JOIN and WHERE
statements).
• To solve the alias issue (alias used in JOIN and WHERE statement),
we have to modify the initial query:
SELECT
ARTIKEL = t.APLAN,
BELEG = t.BAUFTRAG,
t.POSITION,
t.AG ,
ISNULL( t.T_IST , 0 ) AS ISTZEIT ,
ISNULL ( t.T_REST , 0 ) AS T_REST ,
ISNULL ( t.T_SOLL , 0 ) AS SOLLZEIT ,
t.START ,
ISNULL ( t.MENGE , 0 ) AS SOLMENGE ,
ISNULL ( t.MENGE_IST , 0 ) AS ISTMENGE ,
ISNULL ( t.TEPMNG , 1 ) AS TEPMNG ,
ISNULL ( t.MAGR , '(NULL)' ) AS MAGR ,
ISNULL ( t.KOST , '(NULL)' ) AS KOST ,
ISNULL ( t.TE , 0 ) AS TE ,
PROJEKT = COALESCE ( t.projekt , kopf.projekt , '(NULL)' ) ,
ARTIKELNAME = a.name ,
t.KOSTENGRUPPE ,
t.STATUS ,
t.PRIORITAET ,
MAGRNAME = m.name ,
KOSTNAME = k.name_kost ,
ISNULL ( t.ENDE , '01.01.1900' ) AS ENDE
FROM wauftragpos AS t
JOIN WAUFTRAG KOPF ON t.bauftrag = KOPF.bauftrag AND
t.position = KOPF.position
LEFT OUTER JOIN artikel a ON t.aplan = a.artikel
LEFT OUTER JOIN magr m ON t.magr = m.magr AND t.kost =
m.kost
LEFT OUTER JOIN kost k ON t.kost = k.kost

• and use the query that uses the derived table:

SELECT * FROM (
SELECT
ARTIKEL = t.APLAN,
BELEG = t.BAUFTRAG,
t.POSITION AS WAUFTRAG,
t.AG ,
ISNULL( t.T_IST , 0 ) AS ISTZEIT ,
ISNULL ( t.T_REST , 0 ) AS T_REST ,
ISNULL ( t.T_SOLL , 0 ) AS SOLLZEIT ,
t.START ,
ISNULL ( t.MENGE , 0 ) AS SOLMENGE ,
ISNULL ( t.MENGE_IST , 0 ) AS ISTMENGE ,
ISNULL ( t.TEPMNG , 1 ) AS TEPMNG ,
ISNULL ( t.MAGR , '(NULL)' ) AS MAGR ,
ISNULL ( t.KOST , '(NULL)' ) AS KOST ,
ISNULL ( t.TE , 0 ) AS TE ,
PROJEKT = COALESCE ( t.projekt , kopf.projekt , '(NULL)' ) ,
ARTIKELNAME = a.name ,
t.KOSTENGRUPPE ,
t.STATUS ,
t.PRIORITAET ,
MAGRNAME = m.name ,
KOSTNAME = k.name_kost ,
ISNULL ( t.ENDE , '01.01.1900' ) AS ENDE
FROM wauftragpos AS t
JOIN WAUFTRAG KOPF ON t.bauftrag = KOPF.bauftrag AND
t.position = KOPF.position
LEFT OUTER JOIN artikel a ON t.aplan = a.artikel
LEFT OUTER JOIN magr m ON t.magr = m.magr AND t.kost =
m.kost
LEFT OUTER JOIN kost k ON t.kost = k.kost) AS DERIVED
WHERE $P{where}
• the POSITION field was aliased to WAUFTRAG.
• the original query is used as a derived table.
• the alias WAUFTRAG is used in JOIN and can be used in the WHERE
statement or inside the report parameter $P{where}.
• For example the $P{where} parameter containing the string
WAUFTRAG=[10;10]
would be expanded by apqe to
( ( derived.WAUFTRAG >= N'10' AND derived.WAUFTRAG <=

N'10' ) )

Notes Be careful to insert a space between ) and AS, i.e. LEFT OUTER JOIN
kost k ON t.kost = k.kost) AS DERIVED. The string
)AS DERIVED
would cause an exception
java.sql.SQLException: The multi-part identifier "t.WAUFTRAG " could not

be bound.
Don't use the statement parameter
WHERE $P!{where},
always use
WHERE $P{where}
• $P{where} uses an APplus specific where syntax and is processed

by apqe and coverted to SQL syntax.
• $P!{where} is substituted with the parameter value before the

query execution and is not preprocessed by apqe. The parameter is
expanded to:
WHERE WAUFTRAG=[10;10]

How To Customize Search Criteria (On Sel Pages)?
Problem We have to create a statistical report that display the range of data
defined on statistical (Sel) page.
The field used for filtering is not present in the DB table or view.
Solution
Example auftragDetail_sub.jrxml (customized statistical report)
The report is based on the query:

SELECT
FIRMANAME=f.name,
BELEG=t.auftrag,
t.KSTATUS,
t.DATUM,
t.NETTO,
t.FIRMA,
t.VERTRETER,
VERTRETERNAME=v.name,
t.PERSONAL,
t.ANGEBOT,
t.AUFTRAGSART,
VBEREICH=substring(t.auftrag,7,2)
$P!{selFields}
FROM f_auftrag as t
left outer join FIRMA f ON f.firma = t.firma
left outer join vertreter v ON t.vertreter = v.vertreter AND
t.auftragsart = v.auftragsart
left outer join artikel a ON t.artikel = a.artikel
gj.artikelgruppe
$P!{selJoin}
WHERE $P{where}
ORDER BY GRUPPE, MONAT, $P{orderby}, BELEG
• The VBEREICH is used as a field and as a filtering criteria in the
WHERE statement.

• Using the alias in a WHERE statement is a known issue. To avoid

this issue we modify the query using the derived table:
SELECT * FROM (
SELECT
FIRANAME = f.name ,
BELEG = t.auftrag ,
VERTRETENAME = v.name ,
VBEREICH = SUBSTRING ( t.auftrag , 7 , 2 ) ,
t.KSTATUS ,
t.VERTRETER ,
t.PERSONAL ,
t.FIRMA ,
t.RADRESSE,
t.PLZ,
t.PROJEKT,
t.ARTIKEL,
a.NAME,
t.ARTIKELGRUPPE,
a.SACHGRUPPE,
t.DATUM ,
t.TERMIN,
t.NETTO ,
t.MANDANT,
t.ANGEBOT ,
t.AUFTRAGSART,
t.STATUS,
t.POSITIONSART,
t.WAEHRUNG
$P!{selFields}
FROM f_auftrag as t
left outer join FIRMA f ON f.firma = t.firma
left outer join vertreter v ON t.vertreter = v.vertreter AND
t.auftragsart = v.auftragsart
left outer join artikel a ON t.artikel = a.artikel
gj.artikelgruppe
$P!{selJoin}
) AS derived
WHERE $P{where}
ORDER BY GRUPPE, MONAT, $P{orderby}, BELEG

Notes The SQL query has to contain
• all the fields that are used in the report.
• the fields that may be used as filtering criteria (present in the

WHERE statement (i.e. all the fields that are defined in the
auftragSel page)).
Special care must be taken to prevent double definition of the fields in

the query. Note that some fields are inserted at run-time
($P!{selFields} parameter) from the file SelFields.xml.
• The Auftrag statistical report supports several analysis types. Each

analysis type is realized with a separate report. When we add a new
filtering field to the Sel page, we must update all corresponding
reports.
All Auftrag statistic reports needed to be updated in the same way

as proposed above (the derived table has to be used in the report
query and fields must be added to the query).
Since the reports don’t have equal queries and have different
definitions of selFields parameter, this has to be done report by
report.
How to Ursprungsland optimization, WS utility class report

usage example
For more information about Ursprungsland optimization see

How to add new web service class
For more information see Schulungshandbuch APplus Jasper Reports

and Chapter "Anhang 3: Scriptlets und Utility Klassen".
How to measure (WS utility class) performance
For more information see Schulungshandbuch APplus Jasper Reports

and Chapter "Anhang 3: Scriptlets und Utility Klassen".
How to Hide/Display Rows Conditionally
See chapter "Jasper Reports Conditional Column Hiding" on p. 131

How to Hide/Display Column Conditionally
See the examples
• BestellungLang and
• AuftragLang
in the chapter "Jasper Reports Conditional Column Hiding" on p. 131.
How to Use Bands for Table Modeling?
See chapter "Authoring" on p. 55
How to Activate apqe Logging?
See chapter "AP Query Executer (APQE)" on p. 137
How to Debug apqe?
How to Use Jahresvergleich?
How to Perform Culture-sensitive Formatting?
• How to perform Culture-sensitive Formatting
• APpus standard formatting
• Custom formatting
See section "How to Perform Culture-sensitive Formatting?" on p. 86
How to Set Report Locale?
See section "How Is the Localization of a Report Set …" on p. 91

How to Create Default Resource Bundle?
See chapter "Jasper Report Internalization Q&A" on p. 85
How to Create/Update/Translate Resource Bundle for a

New Language?
How Do We Localize Texts in Reports?
How to Deploy a Report and Resource Bundle(s)?
How to Select a Report Language on the JasperServer?
How to Select a Language for Printed Documents?
How to Select a Language for Previewed Documents?
How to Select a Statistical Report Name?
See chapter "Jasper Report Integration" on p. 25

How to Enable Print/Preview for Statistical Analysis?
How to Determine Needed Entries in SelParts.xml?
How to Change/Add the Report Format (e.g. HTML)?
How to Pass Custom Parameters to Statistical Reports?
How to Mapping an Old JobTask (WORD, RS, IE) to a

JasperReports JobTask?
How to Create a Serial Print Job?
How to Customize the Print/Preview Flow?
How to Pass Custom Parameters to Doc, List, Out Reports?

How to Configure Report Run Permission?
See chapter "Security" on p. 159
Display a Value as Duration
Requirements A value that is passed in seconds has to be displayed in this format
##:##:##
So far there exists no scriptlet, which could be applied. Also by using

patterns was no suitable option found.
Solution An Attempt at a solution you can see in the report srAplanDetails used
in the report aplan.
Use a text field with an expression where the hours, minutes and
remaining seconds are determined manually. In the output of each
them will be separated by colons.
Example Here is an example for the field TR:

String.valueOf(new
DecimalFormat("00").format($F{TR}.intValue() / 3600)) + ":"
+
String.valueOf(new
DecimalFormat("00").format(($F{TR}.intValue() -
(($F{TR}.intValue() / 3600) * 3600)) / 60)) + ":" +
String.valueOf(new
DecimalFormat("00").format(($F{TR}.intValue() -
(($F{TR}.intValue() / 3600) * 3600) -
(($F{TR}.intValue() - (($F{TR}.intValue() / 3600) * 3600)) /
60) * 60)))
How to Use isnull() in a WHERE Parameter / in the Search

Criteria on Sel.aspx?
Sometimes it is required that search criteria constructed on pages of

statistical analysis uses a isnull() function.
For example the pages of statistical analysis (*Sel.aspx) use the field
DATUM to define a date range in search criteria. We would like that the
field DATUM1 is used when the field DATUM is empty.
The final SQL query would look like this:

SELECT
...
DATUM=isnull(DATUM, DATUM1),
...
FROM table
WHERE (( ( ( ISNULL(table.DATUM, table.DATUM1) >= val1 AND
ISNULL(table.DATUM, table.DATUM1) <= val2 ) ) )

To use the isnull() function in the WHERE condition it is necessary to

define the field names in pages of statistical analysis (*Sel.aspx)
properly:
1. The input node must contain the second name as an attribute e.g.
<input id='DATUM' name='DATUM' name2='FERTIG' dtType="date">
2. The name of the attribute must be name2.
3. The attribute has to contain the name of the second field for the isnull()
function, e.g. the previous example would produce:
isnull(DATUM,FERTIG)
Notes The isnull() function will become part of the WHERE parameter in the
URL:
... &where=isnull(FERTIG%2CDATUM)%3D[2008-11-
11T00%253A00%253A00;2009-11-11T23%253A59%253A59] ...
And the SelCriteria in the subreport will show the isnull() function:
Figure 18-1 SelCriteria in the subreport
To improve the SelCriteria of the output of the subreport add a line to

the file Sel.xml, e.g. add for the example above a line
<inp name="ISNULL(FERTIG,DATUM)" type="date">Datum</inp>
Figure 18-2 Improve the output of the SelCriteria
Examples
A) lagerbewegungsel.aspx - Filtering on isnull(DATUM, FERTIG)
modify
<input id='DATUM' name='DATUM' dtType="date">
to
<input id='DATUM' name='DATUM' name2='FERTIG' dtType="date">
B) lagerbewegungsel.aspx - Filtering on isnull(FERTIG,DATUM)
modify
<input id='DATUM' name='DATUM' dtType="date">
to
<input id='DATUM' name='FERTIG' name2='DATUM' dtType="date">
modify
<input id='DATUMX' name='DATUMX' dtType="date">
to
<input id='DATUMX' name='FERTIGX' dtType="date">

Note:The name for the second input field must end with X, e.g. change
name='FERTIG' to name='FERTIGX'!
C) lagerbelegungsel.aspx - Filtering on EINKAUF (checkbox)
modify
<input type="checkbox" class='P2CHECK' id='EINKAUF' name='EINKAUF' dtType="i2">
to
<input type="checkbox" class='P2CHECK' id='EINKAUF' name='EINKAUF' name2='FIELD2'
dtType="i2">

How to Solve the Issues of the Field Reader in iReport?
In this section there will be discussed known limitations of apqe of the

field reader.
Issue 1 The Select statement will be augmented with an additional column

(adress.anrede).
The lower part of the window in iReport shows that there is a problem.
If you press the button Read Fields, it produces no change.
Solution The problem was caused by an undefined parameter value. The

parameter was used in the report query. Since the value was not
defined the Field Reader code reported an error. The implementation of
the field reader expected that all parameters that were present in the
report query had to have a default value set in order for the field reader
to get the fields.
The field reader was modified and returns now the field list regardless
of the values of the definition of the parameter.
Issue 2 Bei Statistiken, muss ich bei einer Erweiterung immer alle Parameter
(wieder) vorbelegen und danach wieder entfernen (selgroup etc.). Evtl.
gibt es ja noch eine praxistauglichere Lösung.
If you augment reports for statistical analysis, you must always

preallocate all parameters and then remove them again (selgroup etc.).
Possibly. Perhaps there is a more practically solution for this problem.
Solution The field reader was enhanced. It is enough to define the value of the
selGroup parameter (i.e. grouping criteria). The selFields and selJoin
parameters are read from SelParts.xml.
Precondition The file SelParts.xml contains the definitions for the reports for
statistical analysis.
Verification
1. Set a default value for the selGroup parameter, e.g. "artikel".
2. Leave the selFields and selJoin parameters empty.
3. Open the Query Editor and press the button Read Fields.


Index
APplusStyles Template 110

appserver 137
_ AppServer Adresse 51
apqe 137
_auswertung execution contexts 138
values 30 external dependencies 138, 146
Jahresvergleich 150
A query language 42, 43
tasks 137
Access Rights
apqe logging
JasperServer 161
iReport 148
AccessRight 159
JasperServer 148
Ad Hoc Editor 167, 168
apqe registration
ad hoc reporting 167
iReport 154
tool 167
JasperServer 153
Ad Hoc reports
apqe, debug
iReports 170
iReport 149
Analysis 10
with service 149
Analysis type
without service 149
Report design 26
apqe, debug: 149
AP Extension Plugin 82
APQueryExecuter 16
AP extensions 42
APQueryExecuterFactory
AP Query Executor 42
Tasks 145
AP SQL query executer 139
APQueryExecuterFieldsProvider 145
APCustomJSReportService 16, 43, 131, 132,
APReportExtensionsPlugin 16, 49, 132
155, 157
Configuration 49
APCustomJSReportService.jar 132, 156
Setup 49
APJasperExtensions 16
APReportExtensionsPlugin.jar 43
APJasperExtensions jar 132, 157, 162
APReportLocalizerPlugin 16, 43, 52, 53
APJasperExtensions.jar 41, 43, 132, 156
APReportRunExtension 16, 43, 52
APMandantQueryExecuter 143
Functionality 52
Parameter 143
Report Run 52
Syntax 143
APReportRunExtensionPlugin 132, 157
applicationContext.xml 42, 44, 155
APReportsScriptlets 17
applicationContext-security.xml 42, 44, 162
APSelinfoQueryExecuter 141
APplus authorization filter 42
Parameter 141
APplus configuration
Syntax 141
applus.config.xml 42
APSqlQueryExecuter 139, 145
APplus configuration file 43
APUserContext 145
APplus Integration
APWebServiceFactory 146
JasperServer 15
APWebserviceQueryExecuter 144
APplus plugin 43
Function Parameter 144
APplus Print Service 123
Limitation 144
APplus Security Manager 159
Parameter 144
applus.config.xml 42, 43, 44, 45, 50, 137, 146
Syntax 144
customizing 147
authentication filter 159
APplusAuthFilter 16, 161, 162
authorization filter 42
APplusPrintService 17
Autorisierung 165
APplusStyles 116
Technical Description JasperReports Index • 189

B Report designs 35
Document
barcode4j.jar 41, 43
Language selection 100
Print 101
C Document output
checked permissions 159 PDF 113
class diagram 128 Document, preview
print server application 128 Language selection 102
classpath 51 Domain
configuration, dynamic 49 Ad Hoc Reporting 168
Common
Tab 131 E
conditional colum
Editing
display extension 42
Resource bundle 95
hide extension 42
env 51
conditional column removing 49
Environments for the first instance
Configuration
Systemconfiguration 48
Change 50
exportToPdf() 155
configuration file 43
Configuration files 44
configuration settings F
mandatory 125 features
configuration, basic 126 print server 123
configuration, extended 126 field
Cultural preferences 80 locale dependant 79
Currency Field,Text
field, locale dependent 80 Style 117
Currency formatting 90 fillReport
Custom Method 132
formatting 89 filterHTML() 119
custom parameters 39 Font
report 34 Unicode 115
custom PDF exporter 42 Font Name 116
Custom tools Font Path 115
reports, localize 82 Font properties 116
CustomAuthenticationFilter 162, 163 Font Properties 113
customize Font, custom (TTF)
preview flow 38 PDF Document 114
print flow 38 Font,inherited
Customized serial printing 37 Operation system 114
fontmap.xml 45, 115, 156, 157, 158
D Formatting
APplus standard 88
data, locale dependent
Formatting,culture-sensitive 86
rendering 93
Date
field, locale dependent 81 G
formatting 88 Global Style Template 111
date field 89
Default style 104
I
Definitionen
folder 165 Identity-H 116
design process Implementation notes
Ad Hoc Reporting 169 Sel.aspx 29
different groupings 25 installation
DocTypes.xml print server 125
Report names 35 Internationalization 79
DocTypes.xml 35 iReport
document Quick facts 11
190 • Index Technical Description JasperReports

report localization 82 jtds.jar 41, 43

Run report flow 23
Server interaction 22 L
iReport Integration 132
Is styled text attribute 120 Life Cycle
Jasper Report 24
list
J
Report designs 35
Jahresvergleich Local report directory 51
*Sel.aspx page 151 Localization
apqe 150 JasperServer 94
report 151 Localization 79
Jasper Integration 44 Localizer 82
Jasper Intregration log4j.properties 44, 45
APplus 41 logging
JasperServer 41 print server 123
Jasper Report
Life Cycle 24 M
Permission Setup 165
JasperReports Managed Reporting 10
Overview 10 MANDANT 137
jasperreports.properties 44, 45 Markup attribute 118
JasperServer Markup LI
APplus Integration 15 Issue 122
JasperServer 12 Markup LI
Quick facts 13 Workaround 122
Shared Services 12 Mass Localizer 82
JasperServer module 36
Localization 94 multiple analysis types 25
JasperServer
Access Rights 161 N
JasperServer
Name generation process
Login Page 163
Report name 26
JasperServer installation path
Naming convention
Report name 26
JasperServer Integration 132
new operation
JasperServer Password
report 166
new role
JasperServer reporting for SQL
add 165
Nodes
JasperServer URL
SelParts.xml 27
NT LAN Manager 161
JasperServer user
Number
field, locale dependent 80
JasperSoft BI Suite
Number formatting 90
Fundamentals 9
Numbers
JasperSoft Business Intelligence Suite 9
formatting 88
JasperSoft Capabilities 9
JasperSoft Products 9
jobASP 36 O
jobDotFile 36 Open Source 13
jobFormat 36 Operation flow
jobTask 36 Preview 19
jobUserParam 36 Operation flow
JR 36 Print operation 21
JRBELEG 36 Operational Reporting 10
JRJdbcQueryExecuter 139 out
JRLIST 36 Report designs 35
JRXML file 168

P R
P2plusJS.aspx 36 redistribute
P2QueryUtils 145 removeColumns parameter 133
p2user 51, 137 remove
P2WebUtils 145 removeColumns parameter 133
Pattern editor remove column
Formatting,culture-sensitive 87 example 133
Pattern, dropdown list limitations 133
Formatting,culture-sensitive 86 removeColumns
PDF parameter 132
Document output 113 Parameter 132
PDF Document removeColumns parameter 131
Unicode Text 115 rendering
PDF Embedded 114, 116 data, locale dependent 93
PDF Encoding 114, 116 report
PDF export 49 new operation 166
PDF Export report authoring 169
Styled Text 121 Report design
PDF export of HTML texts 157 Analysis type 26
PDF file Report Design
Reportexport 114 formatting,culture-sensitive 85
PDF font map 42, 43 Report designs 35
PDF Font Name 114, 116 report editing
PDF output Ad Hoc Editor 170
bold 155 Report format, predefined
HTML tag 155 Statistical analysis 33
italic 155 Report language
pdfFontMapLocation 157 JasperServer 98
pdfFontMapName 157 Report localization support 49
Percent formatting 90 Report name
permission checking Name generation process 26
APplusAuthFilter 162 Report name
permission checks 159 Naming convention 26
Permission Setup Report name
Jasper Report 165 Selection process 31
Preview Report names
Operation flow 19 DocTypes.xml 35
Preview operation Report parameter 39, 51
Server interaction 18 report permission
print flow configuration 160
customize 38 verification 161
Print operation Report processing 131
Operation flow 21 report run
Server interaction 20 Ad Hoc report 170
print server report storing
javadoc documentation 128 Ad Hoc Reporting 170
print server Report style 103
features 123 Report Styles
installation 125 Cascading 104
requirements 124 Report, deploy
start 127 JasperServer 96
Windows service 128 REPORT_LOCALE 80, 94
Print when expression 131, 133 parameter 91
Professional Eition 13 Reportexport
properties 50 PDF file 114
reportFill()
Q method 132
Reporting Services statistik report
query language 137 Systemconfiguration 46

Repository plug-in 82 SPRACHE column 91

requirements statistic report name 31
print server 124 Statistic reports 25
Resource bundle 81 Statistical analysis
Adding 95 Preview 32
Creating 95 Print 32
Edit 95 Statistical reports 93
Editing 95 Style
Translate 95 defining 105
Resource bundle, deploy Style name 104
JasperServer 97 Style Template
resource bundles 79 Creating 106
role Style Template 106
permissions, add 166 Style Template
Rollen - Aufgaben - Operationen 165 Style, adding 108
Run report flow Style Template
iReport 23 Style, using 109
Run time view 18 Style, new
define 103
S Style, reusing 105
Styles, conditional 104
Save preview in DMS systemconfiguration 126
security filter
T
JasperServer 161
Sel.aspx Text field
Implementation notes 29 properties 89
sel.xml 42, 43 Text, static 117
Sel.xml 141 Text, static
sel_<company_name> .xml 45 Style 117
sel_<company_name>.xml 44 The first instance
Sel_<company_name>.xml 146 Systemconfiguration 48
SELECT 137 Time
Selection process field, locale dependent 81
Report name 31 time field 89
selFields 53 Tomcat server
selGroup 53 JDK 1.6 162
SELINFO 137 tool
selobj ad hoc reporting 167
values 30 Topic creation 169
selParts.xml 53 Topics
SelParts.xml 27, 42, 43, 137 Ad Hoc Reporting 168
Entries 33 TTF files
Nodes 27 Classpath 114
SelParts_<company_name> .xml 45
SelParts_<company_name>.xml 45, 146 U
sequence diagram 128
serial print job Übersetzung plug-in 82
create 37 Unicode
DocTypes.xml 37 Font 115
Server information 51 Unicode Text
Server interaction PDF Document 115
Preview operation 18 user authorization 159
Print operation 20 Users of the first instance
Server interaction Systemconfiguration 48
iReport 22
Setting of 46 V
Shared Services
Verify report
JasperServer 12
formatting,culture-sensitive 85

WebServer Adresse 51
WEBSERVICE 137
Zugriffsrechte 165


TB APplus JasperReports

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

TB APplus JasperReports

Uploaded by

Copyright:

Available Formats

Technical Description

Jasper Report Integration 25

Jasper Reports Production 41

Technical Description JasperReports Content • 3

iReport AP Extension Plugin 49

Jasper Report Internationalization 79

Jasper Report Internalization Q&A 85

4 • Content Technical Description JasperReports

How Is the Localization of a Report Set … ..........................................................................91

Jasper Reports Working with Fonts 113

APplus Print Service 123

Jasper Reports Conditional Column Hiding 131

Technical Description JasperReports Content • 5

Using Special Report Design ...........................................................................................135

AP Query Executer (APQE) 137

Custom PDF exporter 155

Jasper Report Permission Setup 165

Ad Hoc Reporting 167

Jasper Reports How To 173

6 • Content Technical Description JasperReports

How to add new web service class...................................................................................180

Technical Description JasperReports Content • 7

8 • Content Technical Description JasperReports

Overview The JasperSoft Business Intelligence Suite is a comprehensive Business

Figure 1-1 Overview Of the JasperSoft Business Intelligence Suite

The JasperSoft Business Intelligence Suite brings sophisticated

• Extensibility through open source

• Configurable and replaceable user interfaces

Technical Description JasperReports JasperSoft Products • 9

Operational Reporting • Graphical report design tool

• Subreport inclusion for complex reports and dashboards

• Multiple data sources within a single report

• Custom calculations and variables

• Unlimited report size / report virtualization

Managed Reporting • Interactive, parameterized report generation

• Automated report distribution

• Managed ad-hoc data access

Interactive Analysis / • Data exploration: Drill-down, roll-up, "slice-and-dice", pivot, filter

• Data visualization: multidimensional tables and charts

• Links to detailed reports and other online resources

• Standard XML/A data access protocol and MDX query language

About JasperReports JasperReports is a Java reporting library. The JasperReports library is

Quick Facts • Is a Java reporting library.

• Is the reporting engine embedded in the JasperSoft Business

• Open Source edition can be downloaded from

• Fully supported Professional and Developer Editions available.

10 • JasperSoft Products Technical Description JasperReports

iReport – Graphical Report Designer

About iReport iReport is a graphical report designer for JasperReports and

Quick Facts iReport

• is used by report developers and power users.

• exposes and makes it easier to use the JasperReports library.

• integrates with the JasperServer to allow report developers to

• Open Source edition (iReport) can be downloaded from

• available in Professional and Developer Editions with JasperReports.

Figure 1-2 iReport

Technical Description JasperReports JasperSoft Products • 11

JasperServer – Interactive Reporting Server

JasperServer is a stand-alone and embeds ad hoc and interactive

• Security services: Built-in authentication, or single sign-on

• Repository services: Robust and scalable secure object storage for a

• User interfaces: All out-of-the-box user interfaces applications can

• Scheduling services: Built-in scheduling service provides for offline

Figure 1-3 JasperServer