Welcome to the JReport Server User`s Guide

Welcome to the JReport Server User`s Guide
Welcome to the JReport Server User's
Guide
This User's Guide describes JReport Server. JReport Server is a 100% Java report generation and
management tool that can be deployed to any Java EE application server. By leveraging its high
performance report generation engine, JReport scales to meet the most demanding requirements.
Using the report scheduling, distributing and alerting capabilities of JReport Server, reporting can be
integrated into the workflow of the application.
This guide is written for report administrators or system administrators of Java application that embed
JReport reports into their application.
Other JReport documentation
This guide is one in the complete JReport documentation set. The documentation set includes the
following:
●
Getting Started with JReport
●
JReport Tutorial
●
JReport Server User's Guide
●
JReport Designer User's Guide
●
JReport Server Monitor User's Guide
●
JReport API Javadoc
What's New in This Release
This document introduces the new features and significant enhancements of JReport in this release.
Geo Analysis with OpenStreetMaps and Google Maps
●
Available for JDashboard and Web Report Studio
●
Hierarchical drill up/down
●
Conditional color areas & markers
●
Conditional shapes & sizes
Visualization Enhancements in Dashboards and Reports
●
New HTML5 chart types: heat maps, scrollable real time charts
●
New view modes for Visual Analysis: Fit Height, Fit Width, Fit Visible and Normal View
●
Smart layout enhancements for Visual Analysis to automatically scale tick marks and labels
●
Advanced filters with conditions: and, or, between
●
Conditional linking to different reports, URLs or emails
●
Connect to different data sources from one report
●
Customizable data formats at runtime
●
Quick search for easy location of resources
●
Dynamic resource support (e.g., parameters, formulas, fields) in URLs
Performance and Scalability Improvements
●
Higher volume Ad Hoc and Web reports and dashboards supported by JReport Server Cluster
●
Incremental data fetching when auto refreshing tables and charts
●
Performance optimizations for filtering a large set of dimension members
●
Performance optimizations for rendering charts with large sets of data points
●
Crosstab performance enhancements (i.e., orders of magnitude faster for very large crosstabs)
Resolved/Known Issues in This Release
This document describes the resolved issues and any known issues for JReport in this release.
Resolved issues
Item
Case #
Issue
1
64637
An XML file can now be displayed correctly when using advanced run with a report in
XML format using Internet Explorer 9.
2
64642
An exported Excel file can now be generated normally when user exports a report to
Excel on JReport Server with the option Preserve Report Formatting or Normal
Formatting checked.
3
64697
JReport Designer no longer slows down after the user moves his mouse pointer over a
few report components and then does a few delete and undo actions.
4
64702
JReport Server now uses the correct schema to access the TaskAudit table when they
use two different schemas for the production and development server.
5
64762
Resolved the "HTTP 0" problem when doing page navigation within a tabular
component running on JDashboard which has large volumes of data.
6
64774
The file name of an exported page report can now be correctly displayed.
7
64818
Users can now drag a newly created formula in an ad hoc report that returns a date
type from the Resource View panel to the report.
8
64819
Ad hoc crosstab and chart reports can now be generated normally in JReport Server
when setting the property Push Down Group Query to true on JReport Designer catalog
and Automatic Cache has been checked on the JReport Administration page.
9
64821
The web report Export dialog and Select Field dialog can now be resized and the dialog
buttons can be displayed completely under IE Compatibility View mode or when the
Document Mode of IE is Quirks.
10
64849
Grant "Visible" permission only on new users to access resources controlled by Member
Level Security during ad hoc reporting.
11
64859
The data in pie charts running on JDashboard are now displayed properly in Firefox
when two values are equal or close to equal.
12
64865
JReport Server now uses the data order from the database when user sets the sort
order on the category axis of a chart to No Sort.
13
64877
Now the title of the dashboard filter control can be displayed normally when the
dataset for the filter is empty.
14
64879
Enhanced JReport Server performance when a constant interval is used in the charts to
label the tick marks.
15
64882
The JReport Administration page is now displayed without error after user upgrades
JReport Server 11.1 Update 2 to a higher version.
16
64895
Further enhance XSS security to prevent attacks by changing the user's parameter
values via JavaScript.
17
64920
JReport Server now works normally when the same page report is scheduled to print
multiple times with different parameters.
18
64938
Multi-value parameters can now be passed correctly when triggering the created
schedules from another Java standalone program.
19
64940
Everything now works correctly on JReport Server when user clicks the Export or Print
button on the RMI side in an AIX system.
20
64956
Changed the TotalValue of a web table report to 0 if there is no data in it.
21
64956
Changed the TotalValue of a web table report to 0 if there is no data in it.
22
64958
The displaying and formatting of numeric fields in a page report are now kept properly
after the report is published to JReport Server running on Linux system.
23
64964
Parameter control can now work properly in Page Report Studio when the parameter
name contains the special character "@".
24
65010
Resolved the C0FF0001 error that occurs when user creates a web table report and
then selects a field of type "double" after upgrading his JReport Server from V12.1 to a
newer version.
25
65011
Publishing reports or catalogs from JReport Designer to JReport Server no longer
results in java.lang.reflect.InvocationTargetException error.
26
65017
The existed user can now access a report published from JReport Designer by using an
URL directly.
27
65029
The underline display font in an exported PDF file of the report now stays normal after
JReport Server is upgraded to a newer version.
28
65036
User's changes to Profiling DB settings no longer go back to the default ones after
restarting JReport Server.
29
65053
The dotted line and underline in user's page report can now be displayed normally after
the report is exported to PDF in JReport Designer.
30
65073
The national language support feature is now supported on the server Calendar dialog.
31
65082
The exported Excel file can now be opened normally when user exports a report to
Excel with Data Format checked in JReport Designer.
32
65100
Users are now able to export a web report to PDF or Excel format on JReport Server
without getting any error message.
33
65116
Enhanced JReport Server performance when editing operations are being carried out in
a web report that has several components.
34
65127
Protects users from Cross-Site Scripting attacks when they are generating or saving
reports using Internet Explorer 8 or above versions.
35
65136
The ad hoc report can now be opened normally after user inserts a formula in the
report that returns a predefined formula as the result and saves the report.
36
65138
Removed the unwanted links to the worksheets on the first page of the Excel file of a
report which is published from JReport Designer.
37
65139
Running reports in Web Report Studio no longer results in "Out of Range" error.
38
65168
Adding a formula column to a page report in Page Report Studio no longer gets
NullPointerException error.
39
65178
The parameter value user specified in the session of a web report can now work
normally in the empty web report in which the user inserts a table.
40
65178
Applying filter value "between" on a generated web table report no longer gets error if
value is missing in one of the table fields.
41
65178
User can now successfully customize the style name and icon in the page report
wizard.
42
65198
JReport Designer API no longer gets an out of memory error when modifying reports.
43
65212
Run Host/Port information can now be displayed normally in the status table of the
running reports in JReport Server Monitor.
44
65240
JReport Server now hides the location of the library component and prompts "You are
not authorized to see this content xxx" if user tries to access the library component he
is not granted permission on.
45
65249
The parameter error info is now localizable using NLS in user's page report.
46
65254
Any user that does not exist on the Security-User panel of the JReport Administration
page cannot log onto the JReport Console page with an existing user's password.
47
65257
The values of the specified fields in the web report filter control can now be displayed
normally when user applies a web filter in which a date value with improper format has
been used.
48
65276
Exporting a report to Excel with the option Column Format checked when running
JReport Server as a war file in an application server no longer results in jet.export.
ExpException error.
49
65282
Now the legend entry label specified via a condition in the web chart report can be
displayed correctly on Web Report Studio and JDashboard after the report is published
to JReport Server.
50
65284
User's created count summary for the table column in a page report now returns 0
instead of null value if all the values in the table column are null.
51
65286
A multi-value parameter in the page report now works properly after creating the
parameter on JReport Designer with the Display Type setting to List and then publish
the report to JReport Server.
52
65287
JReport Designer now works normally when user tries to add a new category to the
report cube by clicking the Insert Category button in the Report Cube Editor window.
53
65291
JReport Server no longer throws an SQL exception when users do drill-down actions on
a library component running on JDashboard with a computed column being used in the
query and the property Push Down Group Query being set to true in JReport Designer.
54
65313
The measure in a web report or library component now has the same group level with
category or series when user sets category/series Top N based on a measure.
55
65338
Trailing blanks no longer get trimmed in the CSV format Text file of a page/web report
or a library component running on JDashboard.
56
65349
JReport Designer now generates correct font faces in Excel 97-2003 workbook (*.xls)
format result files.
57
65362
No longer see the "java.lang.NoClassDefFoundError: deIndent" error that occurs when
deploying JReport Server 12 WAR file to IBM WebSphere 8.5.5.1 and then previews
report printing.
58
65373
Resolved the OutOfMemory error when opening a large catalog in JReport Designer.
59
65379
Now all the scheduled tasks can be triggered normally at the user specified time on
JReport Server.
60
65397
The calendar for the parameter control in a web or page report now works properly
when NLS is used in the report.
61
65467
JReport Server no longer occasionally throws the ArrayIndexOutOfBoundsException
error when multiple users click simultaneously on the My Tasks tab on the system
toolbar of the JReport Console page or just one user double-clicks on it.
62
65476
Now even in case the business view is created based on UDS or imported SQL, users
are allowed to select parameters and special fields in the Predefined Filter dialog and
Edit Filter dialog on JReport Designer.
63
65482
The page/web report result can now be published to fax without any problem.
64
65489
JReport Server now supports using locales that use comma as the
decimal separator such as German to set cube memory for in-memory cubes in the
Cube > Configuration panel of the JReport Administration page.
65
65491
Accessing the page report wizard by using a URL directly on JReport Server V12.1
Update 2.1 no longer results in an unknown exception.
66
65518
JReport Server now allows users to customize the CSS style in <server_install_root>
\public_html\webos\style to change the dashboard main background color.
67
65522
Linking to report from a web crosstab report and then clicking the back arrow on Web
Report Studio no longer results in an error page.
68
65530
Remove temp files in <server_install_root>\history when shutting down JReport
Server running in JBoss.
69
65579
The category name on a dial gauge chart in JDashboard and Web Report Studio can
now be center aligned.
70
65583
Page reports with multi-value parameters are now loading properly when accessing
them by using URLs directly.
71
65586
Exporting a JReport result file of a page report that has images in its subreport to PDF
format no longer results in java.lang.NullPointerException error.
Known issues
Summary field disappears from design view when deleting table column
If a summary is inserted in the GroupFooterPanel of a table, when you delete a column from the table,
or unmerge the cell of the group footer row, sometimes you may find the summary field disappears
from design view, however, from the report structure tree in the Report Inspector, you can still find the
object. You can reset its coordinate related properties so as to make the summary field display again.
Compiling formulas in JReport under JDK 6 or higher gets warnings
Since generic type is introduced to JDK 6 or higher version, when compiling formulas in JReport under
JDK 6 or higher, you may come across warning messages as follows:
●
Note: Test.java uses unchecked or unsafe operations.
●
Note: Recompile with -Xlint:unchecked for details.
You may see that the situations are logged as Javac errors. However, the warning messages do not
prevent Javac from creating .class files and reports can still run correctly.
In this case, you can simply ignore the messages and logged errors.
TOC Browser tree doesn't work well for reports with cached report bursting
When end user runs a report which has been defined with some cached report bursting policy in Page
Report Studio, and then opens the TOC Browser, he will see all the groups of the report instead of just
the ones he is supposed to view. In addition, no matter if he has access to a group, he cannot click the
group name from the TOC tree to get corresponding details. JReport will further enhance the cached
report bursting feature in a future release to resolve this issue.
Report data gets cut off in PDF result
When you export a report to PDF format, if the report contains a large amount of data but its page
mode was specified to be continuous page mode, or its page size was set to be larger than 200 inches,
you will find that in the PDF result some data of the report are cut off. This is because in one PDF page,
the data displayed can be no larger than 200 inches.
Starting JReport with 64-bit JDK 1.7
To use 64-bit JDK 1.7 to start JReport on 64-bit Sun Solaris System, you need to modify the launch
script JReport.sh (for JReport Designer) or JRServer.sh (for JReport Server) in $REPORTHOME/bin by
changing the value $JAVAHOME/bin/java to $JAVAHOME/bin/amd64/java.
Deploying monitor.war (servlet.war) and jreport.war in the same domain gets exception
When integrating JReport Server and JReport Server Monitor into one application server, you need to
make sure that they are deployed to different domains. JReport Server Monitor is supposed to be just
an application for the administrator which doesn't need to come along with a JReport Server as the
report system. So it is recommended that JReport Server Monitor be installed on a separate system or
on systems for system administrators.
Limitation of going to another group on chart
When you perform the go-to action on a chart which uses a dynamic formula as its shown value, and
the formula contains group information, you will get exceptions. This is a limitation in current version.
We will resolve the issue in future release.
The zooming in or out of JReport browsers is not supported
All JReport browsers such as Page Report Studio, Web Report Studio, JDashboard and so on do not
support being zoomed in or out by the way of scrolling the mouse while holding the Ctrl key. This may
result in that the JReport UI cannot display well.
Derby cannot auto start in cross-computer integration
By default, JReport Server uses the embedded Derby as the system database, and automatically starts
the Derby database server (the start of Derby requires the JDK path). If you build a WAR/EAR on
computer A and then integrate it into an application server on computer B, it is probable that the Derby
database server cannot auto start using the JDK path on computer A. If you want to use Derby in an
integration environment, please take the following steps:
1. Build a WAR(jreport.war)/EAR(jreport.ear) on computer A using the following commands:
makewar.bat -Dreporthome=%REPORTHOME%
makewar.bat buildEar -Dreporthome=%REPORTHOME%
2. Deploy jreport.war/jreport.ear to the application server on computer B.
3. In %ReportHome%\derby\bin, modify javahome in the env.bat file to make it the same as that of
computer B.
4. Access the URL http://ip:port/jreport to start JReport Server, and Derby will also get started.
API change
jet.formula.ParamDesc.value has been set to private now. You can use getDisplayValue(DbValue
paramvalue, java.util.Locale locale) instead.
For example:
ParamDesc desc = new ParamDesc();
... ...
desc.getDisplayValue(desc.getValue(), Locale.getDefault());
JReport Product Overview
JReport delivers operational business intelligence to enterprise applications through powerful embedded reporting.
JReport is a complete Java reporting solution that provides sophisticated enterprise reporting, ad hoc reporting, and
data analysis. A 100% Java EE architecture and a rich set of APIs allow JReport to be seamlessly embedded into any
application, providing end users with a transparent interface to easily generate reports, share information, and
analyze data. With JReport, any report can be made interactive, extending the "life" of a report by allowing users to
easily sort, group, navigate, and filter via the Web. This wide range of functionality, including the ability to drill down
on data, enables users to quickly derive value from their business intelligence.
JReport product architecture
JReport's Java architecture takes advantage of the portability, scalability, and ease of integration associated with J2EE
technology to provide a powerful, flexible reporting solution that fits perfectly within any architecture.
JReport Designer is a Swing-based Integrated Development Environment (IDE) that enables sophisticated report
design and presentation of critical business data. It provides an intuitive interface, reusable report components,
flexible layout, and a toolset for designing and testing reports. With JReport Designer, you can build reports using
simple drag and drop techniques or by using the Report Wizard. Data can be accessed from any data source to design
and preview reports in order to deliver information to end users in the most relevant and intuitive manner. Rapid
creation and modification of report templates is accomplished by toggling between design mode and view mode where
the report will be displayed with the actual dataset. Once report design is complete, the template is published to the
JReport Server for generation, delivery, and management.
JReport Server is a 100% Java report generation and management tool. It enables efficient management, sharing,
scheduling, versioning, and delivery of reports and enables reporting to be integrated into the workflow of any Java
application. The high-performance engine can scale to any workload. Report results can be saved to a versioning
system, sent to enterprise/workgroup printers, or e-mailed. With JReport, reports can be viewed in any modern
enterprise format including Page Report, Web Report, HTML and standard business documents, such as PDF, Excel,
and RTF.
JDashboard delivers information using a user portal user interface rather than a report. Users can freely choose the
objects they want to display in the dashboard, without having to know how these objects were created, what data
sources to use, what styles to set, etc. A dashboard can hold multiple data components so that when browsing the
dashboard users are able to see multiple data aspects. Within a dashboard, data components are able to
communicate with each other via the message mechanism. This allows actions such as common filters to be applied to
all the components of a dashboard even when coming from different data sources.
Page Report Studio and Web Report Studio enable reports to be accessed through a web browser via Dynamic
HTML, or AJAX. With Page Report Studio and Web Report Studio, reports can be modified using dynamic filter, sort,
and drill capabilities. Using Page Report Studio and Web Report Studio's advanced capabilities, users can drag and
drop columns to and from an existing report, dynamically change chart types, pivot crosstabs, add groups, convert
report components or create an entirely new report.
Visual Analysis is a WYSIWYG product to visualize the result of every step of your work. Simply by dragging and
dropping data fields to the layout module, users are able to experience the detailed building up of crosstabs and
charts step by step visually. The use of colors, sizes, shapes, and pie slices demonstrates the data in rich aspects.
Reporting a problem or requesting a feature
If you are having trouble running JReport Server or encounter any problems during reporting, take the following steps.
1. Check whether the system on which JReport Server is running meets the system requirements.
2. Check the JReport FAQ pages for frequently-asked questions and their solutions.
If the problem persists, report it to Jinfonet Support ([email protected]) with the following information:
1. Describe the precise steps leading to the problem.
2. Run the batch file jrenv.bat in the <install_root>\bin subdirectory. Running this batch file will generate a file
called report.env in the current directory. Send this file to Jinfonet Support. Also, describe the operating
environment, including machine type, CPU, memory, OS, and Java version.
3. If you are running JReport in an integrated Java application server, click the Server Information button
the JReport Administration page to list the environment.
4. Send Jinfonet Support the log file with the recorded JReport Server problems.
❍
❍
For a standalone server
Start JReport with the batch file DJRServer.bat (.sh on Unix). Running this batch file will record the most
detailed logging information and write them to the log files in the <install_root>\logs directory. Try to
reproduce the problem, and send the log files along with the other information.
For an integrated JReport Server
If your JReport Server runs as a servlet inside a Java application server, send the log files generated by the
on
JReport Engine in the application server. When the JReport Servlet is installed, a property file is generated
which is used to define the class and arguments of the JRServlet. For example, if you integrated JReport
Server into WebLogic, find the WebLogic properties file located in the installation path of WebLogic. Edit the file
to use the option -vDebug -vError. Your file should then contain the following content:
vError=true
vDebug=true
In addition, you can also directly add the java option -Dlogall=true (or -DvError=true, -DvDebug=true) to the
java command line within the launch file of the application server.
After restarting your application server, reproduce the problem and send the log files to Support.
5. Send Support the log files recording all of the logging information of engine and server (including event, error,
debugging, access, management, and performance).
❍
Change the configuration to record all logging events by starting the server and accessing the JReport
Administration page through http://localhost:8889.
a. Go to the Configuration > Log panel.
b. Set the trace level of all logs to TRIVIAL, and set the error level of all logs to WARN.
c. After that, reproduce your problem and send Support the log files in <install_root>\logs. In addition,
you can also directly modify the logging configuration file LogConfig.properties in <install_root>\bin. If
you set the server property log.config.update to true (all server properties are managed within the file
server.properties in <install_root>\bin), any changes to the configuration file will automatically take
effect at runtime after the specified update interval (set by the server property log.config.update.interval).
❍
If your JReport Server runs as a servlet within a Java application server, in the address bar of a web browser,
type in http://<hostname>/jreport/admin, where jreport is the servlet context path.
6. To reproduce your problem of running reports with JReport Server, we will often need your report, catalog and
data information.
a. Send Support the catalog file (*.cat and *.fml) and the report file *.cls that you are having problems with.
b. In order to resolve technical issues that you have reported, we will need to access your report data so that
we can recreate and analyze the problem. Your database may be very large. However, we will only require
access to the data returned by the query of the troublesome report, and if necessary we will sign a
confidentiality agreement with you. To extract the report data, in the Catalog Browser of JReport Designer,
right-click the query that your report is using, select the menu item Create Cached Query Result. Then,
input the data file name and click the Save button. The query result will then be saved in this file. Send
Support all of the files generated (including the description file).
Visiting web pages for more information
●
●
●
●
●
●
Products information
http://www.jinfonet.com/products
News center
http://www.jinfonet.com/company/news
Demo center
http://www.jinfonet.com/resources/jreport-demo
Products download center
http://www.jinfonet.com/product/download-jreport
White papers
http://www.jinfonet.com/resources/white-papers
JReport product documentation
http://www.jinfonet.com/jreport-documentation
●
●
JReport Javadoc
http://www.jinfonet.com/jreport-documentation
JReport Technical Support center
http://www.jinfonet.com/services/technical-support
Installing and Uninstalling JReport Server
This chapter presents how to install JReport Server using a variety of different methods. It covers
issues associated with installing, removing and solving problems encountered during installation.
●
System requirements
●
JReport licenses
●
Supported report databases
●
Installing using the Installation Wizard
●
Installing silently
●
Installing using the console interface
●
Installing on Unix manually
●
Installing by building a war file on Windows to deploy to Linux/Unix
●
Uninstalling
●
Solving installation problems
●
JReport Server reporthome directory overview
System requirements
The following table displays the basic system requirements for installing JReport Server. Check your
system to make sure that all the requirements are met before installation.
JReport Server System Requirements
Recommended Requirements Minimum Requirements
OS:
Windows x64, Unix x64, Linux
x64, z/Linux64
Windows, Unix, Linux, z/Linux
CPU:
Quad Core processor
Dual Core processor
Free
Memory:
8 GB
2 GB
Free Disk:
10 GB
1 GB
JDK:
6 or above
6 or above
Browser:
Latest Releases
IE 9, Firefox 20, Chrome 23
Reference: Download a JDK version at http://www.oracle.com/technetwork/java/javase/downloads/
index.html.
Notes:
●
●
●
Jinfonet supports Java VMs released by Sun and IBM to run with JReport Server. You can try using
other Java VMs, but their compatibility cannot be guaranteed. Reports of any problems you find with
other Java VMs are welcome.
If you want to use JReport Server on a z/Linux system, you must download the JDK specially used
for IBM from http://www-03.ibm.com/servers/eserver/zseries/software/java/ and the version should
be at least V6.
You are not recommended to run JReport in the Internet Explorer Compatibility View mode.
JReport licenses
JReport has several add-on licenses which enable some specific features:
●
JReport Live license
●
JReport Server Cluster license
●
JDashboard license
●
Visual Analysis license
●
Organization license
Contact your Jinfonet Software account manager to obtain your required license.
JReport Live license
The JReport Live license enables the use of web reports and ad hoc page reports and all their related
functions. JReport Designer and JReport Server have separate live licenses.
Live license for JReport Designer
A JReport Live license for JReport Designer controls the data sources for ad hoc page reports and web
reports and the creation of web reports from those data sources on JReport Designer. The Live license
allows you to utilize the following features on JReport Designer:
●
Create and edit report cubes, business cubes, and business views. These are meta-data descriptions
created in JReport Designer to be used as data sources for ad hoc page reports and web reports.
They can be created on any type of data source such as JDBC, ODBC, XML and Web Services.
●
Create web reports from business views.
●
Export and print web reports.
●
The following functions also require that JReport Server has a Live license:
❍
Preview web reports in Web Report Studio.
❍
Publish web reports to JReport Server.
❍
Download reports which use business views, report cubes or business cubes as the data source
from JReport Server.
Live license for JReport Server
A JReport Live license for JReport Server controls the real time ad hoc and analysis reporting on
JReport Server. The Live license allows you to utilize all of the following features and functions on
JReport Server:
●
Create, view, run, edit, export, print, and publish ad hoc page reports and web reports. The data
sources for these reports are created in JReport Designer, which requires JReport Designer has a Live
license.
All actions in Page Report Studio involving report cube/business cube or changes of report template:
●
❍
Create new page reports or page report tabs
❍
Delete report tabs from a page report
❍
Add components and data fields into reports
❍
Remove components from reports
❍
Move and resize components
❍
Edit component properties
❍
Drill
❍
Change chart type
❍
Rotate tables and crosstabs
❍
Convert between crosstab and chart
❍
Create query filters
❍
Display the Resource View panel which shows the data resources for the current open report tab
JReport Server Cluster license
JReport Server Cluster license enables a group of JReport Servers to work together with shared
resources, load balancing, and failover in a distributed cluster.
JDashboard license
A JDashboard license enables the use of JDashboard and all related functions. JReport Designer and
JReport Server have separate JDashboard licenses.
Since JDashboard requires using business views as data sources, the JReport Live license is also
required. JReport Designer and Server have separate Live licenses too.
JDashboard license for JReport Designer
A JDashboard license for JReport Designer allows for creation of library components which are used to
build dashboards and publishing of library components to JReport Server.
JDashboard license for JReport Server
A JDashboard license for JReport Server enables the management of library components in the
component library, the creation of dashboards using library components, and the use of dashboards.
Visual Analysis license
A Visual Analysis license enables the use of Visual Analysis and all related functions. Since Visual
Analysis requires using business view as the data source, the JReport Live license is also needed in
order to perform visual analysis.
Organization license
An organization license enables organizing users into different groups with their own administrators and
dynamic connection management.
Supported report databases
JReport supports all of the current mainstream databases as well as most databases which support
ODBC or JDBC drivers. The following table lists the databases and JDBC drivers that have been tested
with JReport. If you are using any of the databases listed below, you are recommended to use the
corresponding driver version with JReport although any driver which the DBMS supplier recommends is
also fine. If you encounter problems when using a database or driver version that is not listed here,
you can contact Jinfonet Support ([email protected]) for help.
You can also refer to the page http://wiki.netbeans.org/DatabasesAndDrivers for additional information
on database and driver.
Database
Version
Driver File Name
JDBC Driver
Example URL
MS SQL
Server
2012
(11.00.2100)
sqljdbc4.jar
com.microsoft.
sqlserver.jdbc.
SQLServerDriver
jdbc:sqlserver://<host>:1433;
DatabaseName=test
MS SQL
Server
2008R2
(10.50.4000)
sqljdbc4.jar
com.microsoft.
sqlserver.jdbc.
SQLServerDriver
jdbc:sqlserver://<host>:1433;
DatabaseName=test
MS SQL
Server
2008R2
(10.50.4000)
Merlia.jar;
com.inet.tds.
TdsDriver
jdbc:inetdae7:<host>:1433?
database=test
MS SQL
Server
2008
sqljdbc4.jar
com.microsoft.
sqlserver.jdbc.
SQLServerDriver
jdbc:sqlserver://<host>:1433;
DatabaseName=test
MS SQL
Server
2005
sqljdbc.jar
com.microsoft.
sqlserver.jdbc.
SQLServerDriver
jdbc:sqlserver://<host>:1433;user=sa;
password=1234;database=test
MS SQL
Server
2000
msbase.jar; msutil.
jar; mssqlserver.jar
com.microsoft.jdbc. jdbc:microsoft:sqlserver://<host>:1433
sqlserver.
SQLServerDriver
MS SQL
Server
2000
Opta2000.jar
com.inet.tds.
TdsDriver
jdbc:inetdae7:<host>:1433?
database=test
MS SQL
Server
2000
tds-1.0.3.jar
net.sourceforge.
jtds.jdbc.Driver
jdbc:jtds:sqlserver://<host>:1433/test
MySQL
5.5.24 (64bit) mysql-connector-java- com.mysql.jdbc.
5.1.25-bin.jar; mysql- Driver
connector-java-5.1.7bin.jar
jdbc:mysql://<host>:3306/test
MySql
mysql via SSL mysql-connector-java- com.mysql.jdbc.
5.1.6-bin.jar
Driver
jdbc:mysql://db06:3306/test?p?
useSSL=true?
clientCertificateKeyStoreUrl= D:\test
\SSL_Client\ca-cert.pem?
clientCertificateKeyStorePassword=1234
MySql
mysql 5
mysql-connector-java- com.mysql.jdbc.
5.0.4-bin.jar
Driver
jdbc:mysql://<host>:3306/test
MySql
mysql-5.0.2alpha-win
mysql-connector-java- com.mysql.jdbc.
3.1.5-gamma-bin.jar
Driver
jdbc:mysql://<host>:3306/test
MySql
mysql-5.0.18- mysql-connector-java- com.mysql.jdbc.
win32
5.0.3-bin.jar
Driver
jdbc:mysql://<host>:3306/test
MySql
mysql-4.1.12- mysql-connector-java- com.mysql.jdbc.
win32
3.1.10-bin.jar
Driver
jdbc:mysql://<host>:3306/test
MySql
mysql 4
jdbc:mysql://<host>:3306/test
mysql-connector-java- com.mysql.jdbc.
3.0.14-production-bin. Driver
jar
Oracle
11.2.0.1.0
(64bit)
classes12.jar;
ojdbc14.jar; ojdbc5.
jar; ojdbc6.jar
oracle.jdbc.driver.
OracleDriver
jdbc:oracle:thin:@<host>:1521:orcl
(Oracle JDBC Thin using an SID)
Oracle
11.1.0.6.0
(11g)
JDK1.5: ojdbc5.jar;
JDK1.6: ojdbc6.jar;
classes12.jar
oracle.jdbc.
OracleDriver
jdbc:oracle:thin:@<host>:1521:ora11g
Oracle
11.1.0.6.0
(11g)
JDK1.5: ojdbc5.jar;
JDK1.6: ojdbc6.jar;
classes12.jar
oracle.jdbc.
OracleDriver
jdbc:oracle:thin:@//<host>:1521/
ora11gsn (Oracle JDBC Thin using a
ServiceName)
Oracle
11.1.0.6.0
(11g)
JDK1.5: ojdbc5.jar;
JDK1.6: ojdbc6.jar;
classes12.jar
oracle.jdbc.
OracleDriver
jdbc:oracle:thin:@ora11gtn (Oracle JDBC
Thin using a TNSName)
Oracle
10.1.0.2.0
(10g)
JDK1.2&1.3:
classes12.zip;
JDK1.4: ojdbc14.jar
oracle.jdbc.driver.
OracleDriver
jdbc:oracle:thin:@<host>:1521:ora9i
Oracle
9i
JDK1.2&1.3:
classes12.zip;
JDK1.4: ojdbc14.jar
oracle.jdbc.driver.
OracleDriver
jdbc:oracle:thin:@<host>:1521:ora9i
Oracle
8.1.7.0.0
classes12.zip
oracle.jdbc.driver.
OracleDriver
jdbc:oracle:thin:@<host>:1521:userdb
DB2
9.7.200.358
db2jcc4.jar
com.ibm.db2.jcc.
DB2Driver
jdbc:db2://<host>:50000/test
DB2
9.7.0.4
com.ibm.db2.jcc.
db2java.zip; db2jcc.
jar; db2jcc_license_cu. DB2Driver
jar; db2jcc4.jar; sqlj.
zip; sqlj4.zip
jdbc:db2://<host>:50000/test
DB2
9.1.0.356
db2java.zip; db2jcc.
com.ibm.db2.jcc.
jar; db2jcc_javax.jar; DB2Driver
db2jcc_license_cu.jar;
db2policy.jar
jdbc:db2://<host>:50000/test
DB2
8.2
Db2jcc.jar;
db2jcc_license_cu.jar
(Linux, Unix and
Windows);
db2jcc_license_cisuz.
jar (Linux, Unixand
Windows, z/OS,
OS/390,z/OS, iSeries
etc)
com.ibm.db2.jcc.
DB2Driver
jdbc:db2://<host>:50000/test
DB2
8.2
Db2java.zip
com.ibm.db2.jdbc.
app.DB2Driver
jdbc:db2:test
DB2
8.1.9.917
db2java.zip; db2jcc.
com.ibm.db2.jcc.
jar; db2jcc_javax.jar; DB2Driver
db2jcc_license_cisuz.
jar; db2jcc_license_cu.
jar
jdbc:db2://<host>:50000/test
DB2
8.1.7.380
db2java.zip; db2jcc.
com.ibm.db2.jcc.
jar; db2jcc_javax.jar; DB2Driver
db2jcc_license_cisuz.
jar; db2jcc_license_cu.
jar
jdbc:db2://<host>:50000/test
DB2
8.1
Db2java.zip; db2jcc.
jar
com.ibm.db2.jdbc.
net.DB2Driver
jdbc:db2://<host>/test
DB2
8.1
Db2java.zip
com.ibm.db2.jdbc.
app.DB2Driver
jdbc:db2:test
redbrick.jar
redbrick.jdbc.
RBWDriver
jdbc:rbw:protocol:<host>:5050/test/
ifxjdbc.jar
com.informix.jdbc.
IfxDriver
jdbc:informix-sqli://<host>:9088/demo:
INFORMIXSERVER=ol_informix1170
RedBrick
warehouse
Informix
11.70.TC7DE
Informix
11.50.TC7DE
ifxjdbc-g.jar; jdbc.jar
com.informix.jdbc.
IfxDriver
jdbc:informix-sqli://<host>:9090/
informixdatatype:
INFORMIXSERVER=ol_informix
Informix
9.40.TC1E1
ifxjdbc.jar
com.informix.jdbc.
IfxDriver
jdbc:informix-sqli://<host>:1527/Demo:
INFORMIXSERVER=ol_informix
Informix
9.30
ifxjdbc.jar
com.informix.jdbc.
IfxDriver
jdbc:informix-sqli://<host>:1526/
stores_demo:informixserver=DBSC
hsqldb.jar
org.hsqldb.
jdbcDriver
jdbc:hsqldb:D:\JReport\Demo\db
\SampleDB
HSQL
Sybase
12.5.2
jconn2.jar
com.sybase.jdbc2.
jdbc.SybDriver
jdbc:sybase:Tds:<host>:5000/master
Sybase
12.5
jconn2.jar
com.sybase.jdbc2.
jdbc.SybDriver
jdbc:sybase:Tds:<host>:5000/master
Sybase
12.5
jconn3d.jar
com.sybase.jdbc3.
jdbc.SybDriver
jdbc:sybase:Tds:<host>:5000/master
Sybase
11.5
jconn2.jar
com.sybase.jdbc2.
jdbc.SybDriver
jdbc:sybase:Tds:<host>:5000/master
Sybase IQ
15.4.0.3019
jconn3.jar; jconn4.jar
com.sybase.jdbc3.
jdbc.SybDriver
jdbc:sybase:Tds:<host>:2638/iqdemo
PostGre SQL 8.3.0
postgresql-8.3-607.
jdbc2.jar
org.postgresql.
Driver
jdbc:postgresql://<host>:5432/postgres
PostGre SQL 8.2.13
postgresql-8.2-506.
jdbc3.jar
org.postgresql.
Driver
jdbc:postgresql://<host>:5432/postgres
PostGre SQL 8.0
postgresql-8.0-310.
jdbc3.jar
org.postgresql.
Driver
jdbc:postgresql://<host>:5432/test
Cache
Cache 4
CacheDB.jar
com.intersys.jdbc.
CacheDriver
jdbc:Cache://<host>:1972/samples
Derby
10.8.1.2
derby.jar; derbyclient. org.apache.derby.
jar
jdbc.ClientDriver
jdbc:derby://<host>:1528/test
Derby
10.5.3.0
derby.jar; derbyclient. org.apache.derby.
jar
jdbc.ClientDriver
jdbc:derby://<host>:1527/test
Derby
10.5.1.1
derby.jar
jdbc:derby:D:\derby\demo\databases
\toursdb
MongoDB
2.2.2
already within JReport toolkit.db.mongo.
MongoDriver
HIVE
0.10.0
hadoop-commonorg.apache.hadoop. jdbc:hive://<host>:10000
2.0.0-cdh4.1.1.jar;
hive.jdbc.
hadoop-core-2.0.0HiveDriver
mr1-cdh4.1.1.jar;
hive-exec-0.9.0cdh4.1.1.jar; hivejdbc-0.9.0-cdh4.1.1.
jar; hive-metastore0.9.0-cdh4.1.1.jar;
hive-service-0.9.0cdh4.1.1.jar; libfb3030.7.0.jar; libthrift0.7.0.jar; slf4j-api1.6.1.jar; slf4j-simple1.6.1.jar
PSQL
V11 SP3
jpscs.jar; pvjdbc2.dll; com.pervasive.
pvjdbc2.jar; pvjdbc2x. jdbc.v2.Driver
jar
org.apache.derby.
jdbc.
EmbeddedDriver
host, port, databaseName:demo
jdbc:pervasive://<host>:1583/test
Notes:
●
If you want to use the DB2 app connection, you need to install the client and configure the net
address first.
●
●
The database MySql with the example URL jdbc:mysql://db06:3306/test?p?useSSL=true?
clientCertificateKeyStoreUrl=D:\test\SSL_Client\ca-cert.pem?
clientCertificateKeyStorePassword=1234 is connected by SSL. For how to install SSL, refer to
http://www.openssl.org. For how to configure MySql for SSL, refer to http://dev.mysql.com/doc/
refman/5.1/en/ssl-connections.html. For more information about JDBC driver, refer to http://dev.
mysql.com/doc/connector-j/en/connector-j-reference-configuration-properties.html.
For Oracle JDBC Thin using a TNSName, you need to configure the tnsname first, then add the
parameter -Doracle.net.tns_admin=<designer_install_root>\lib into the file JReport.bat which
is located in <designer_install_root>\bin, assuming you have copied the file tnsnames.ora from
your Oracle server to <designer_install_root>\lib.
Installing using the Installation Wizard
Installing JReport Server with the Installation Wizard is intuitive. You only need to follow the screens
and enter the required information. The Installation Wizard provides two installation types:
●
●
Typical Installation for Standalone Server
Installs JReport Server with the default configuration settings.
Custom Installation for Standalone Server
Installs JReport Server in a standalone environment. If you choose this installation type, you can
configure the server system environment in the Installation Wizard.
This document shows you how to install the server to different systems with the Installation Wizard and
configure the server according to your requirements.
Installing on Windows
To install JReport Server on a Windows platform, take the following steps:
1. Download the JReport Server installation file for Windows from the Jinfonet download center:
http://www.jinfonet.com/downloadjreport/.
2. Run the installation file and follow the prompts to install.
During installation, pay attention to the following:
●
●
The installer requires that you choose a Java JDK to complete the installation. You can download the
appropriate JDK from http://java.sun.com or your computer vendors web site.
The Installation Wizard will first find a JVM to get started. If no JVM is found, the JReport installer
will fail to launch. To solve this issue, you can try either way:
❍
❍
Set JAVA_HOME in system environment.
Install JReport Server from a DOS command by specifying the LAX_VM option for the Installation
Wizard as follows:
jrserver-xxx-windows.exe LAX_VM "C:\jdk1.6.0_17\bin\java.exe" (change jrserver-xxxwindows.exe to the real file name of the installation file)
The JDK path should use absolute path and be quoted by "".
●
●
The installer provides a chance for you to add additional class paths. You can also choose to add
them manually into the setenv.bat in <install_root>\bin after installation.
If you select to install JReport Server in a folder that already contains an existing copy, the installer
will replace the packages and create new batch/script files. Meanwhile, a copy of the old batch/script
files will be kept for your reference. You should use the batch/script files that come with the installer
in order to make sure that all new packages are added to the class path and manually merge any
changes you made into the new version.
Installing on Unix
JReport Server supports Solaris, Linux, HP-Unix, and AIX. In the following process, an X server is
running and Java 1.5 or above is available, otherwise ask your administrator for help. Installing and
running JReport Server requires that an X server has been configured.
1. Download the JReport Server installation file for Unix from the Jinfonet download center: http://
www.jinfonet.com/downloadjreport/.
If you need to transfer the installation file from your download machine to your Unix box, you
should transfer it using FTP in binary mode.
2. Click the installation file to launch the Installation Wizard. Alternatively, you can open a console
window, and change the directory to the location of the file. Following are examples of the
commands that can be used:
$ cd /opt/JReport/Server (or your preferred install location)
To make the installation file executable, type the command:
$ chmod +x jrserver-xxx-linux.bin (change jrserver-xxx-linux.bin to the real file name of the
installation file)
To run the installation file:
$ ./jrserver-xxx-linux.bin (change jrserver-xxx-linux.bin to the real file name of the
installation file)
The Installation Wizard will first locate a JVM to get started. If no JVM is found, the installer will
fail to launch. To solve this issue, you can try either way:
❍
Set JAVA_HOME in system environment.
❍
Specify a JVM for Installation Wizard with the option LAX_VM as follows:
$ ./jrserver-xxx-linux.bin LAX_VM "/opt/jdk1.6.0_17/bin/java" (change jrserver-xxxlinux.bin to the real file name of the installation file)
The JDK path should use absolute path and be quoted by "".
3. Once the Installation Wizard has successfully loaded, you can follow the standard prompts to
install JReport Server.
Installing on z/Linux
JReport Server supports Linux on IBM system z. In the following process, an X server is running and a
JDK specially used for IBM is available, otherwise ask your administrator for help. Installing and
running JReport Server requires that an X server has been configured.
1. Download the JReport Server installation file for z/Linux from the Jinfonet download center: http://
www.jinfonet.com/downloadjreport/.
If you need to transfer the installation file from your download machine to your z/Linux box, you
should transfer it using FTP in binary mode.
2. Click the installation file to launch the Installation Wizard. Alternatively, you can open a console
window, and change the directory to the location of the file. Following are examples of the
commands that can be used:
$ cd /opt/JReport/Server (or your preferred install location)
To make the installation file executable, type the command:
$ chmod +x jrserver-xxx-linux.bin (change jrserver-xxx-linux.bin to the real file name of the
installation file)
To run the installation file:
$ ./jrserver-xxx-linux.bin (change jrserver-xxx-linux.bin to the real file name of the
installation file)
The Installation Wizard will first locate a JVM to get started. If no JVM is found, the installer will
fail to launch. To solve this issue, you can try either way:
❍
Set JAVA_HOME in system environment.
❍
Specify a JVM for Installation Wizard with the option LAX_VM as follows:
$ ./jrserver-xxx-linux.bin LAX_VM "/opt/ibm-java2-sdk-6.0/bin/java" (change
jrserver-xxx-linux.bin to the real file name of the installation file)
The JDK path should use absolute path and be quoted by "".
3. Once the Installation Wizard has successfully loaded, you can follow the standard prompts to
install JReport Server.
Configuring system database
Configuring the system database is a step on the server installation wizard available to a production
key or a temporary key.
By default the trial database Derby is used. The port is configurable in case it is being used.
However in a production environment, you'd better configure your own production DBMS instead of
using the default Derby which is provided for testing and evaluation purposes only and which should
not be used in a production system. To do this, select Production Database and then set the correct
database connection information. If the connection failed after clicking Next, a message will pop up,
you can choose to reset the connection. Or if you choose to continue with the failure, after the
installation, you need to configure the database still. For details, see Configuring the server database.
These databases have been tested workable as the production database: HSQLDB, MySQL, Microsoft
SQL Server, IBM DB2, Oracle, Sybase, and Informix.
Notes:
●
●
ODBC is not supported as the server database.
When setting SQL 2000 as the server database, the driver should use jtds.jar, otherwise the
scheduling feature cannot work.
Configuring system environment
When installing JReport Server using the Installation Wizard, if you choose Custom Installation for
Standalone Server, you can configure the server system environment according to your requirements
during the installation. You can configure the following items:
●
Service
●
Cluster
●
E-mail
●
Cache
❍
Cache Loaded Catalogs
Specifies whether to keep a catalog in memory, or to remove it from memory after a report is
completed.
Normally, after a report has been generated, the catalog that is used to generate the report will be
removed from memory. However, if you specify this option, the catalog will be cached rather than
removed.
Cache Loaded Reports
Specifies whether to keep the reports in memory or remove them from memory after they have
been generated.
●
Performance
Pre-loading the Java classes and fonts which are used by catalogs, reports and JReport Engine at
startup time will improve performance when these classes are needed at runtime.
❍
❍
❍
❍
❍
●
Preload Catalog Referred Classes
Pre-loads the Java classes that are used for a catalog.
Preload Report Referred Classes
Pre-loads the Java classes that are used for a report.
Preload Engine Referred Classes
Pre-loads the Java classes that are used by JReport Engine to generate reports.
Preload Fonts
Specifies to load the fonts when JReport Server is started rather than when they are first used.
Maximum Number of Concurrent Reports in the Queue
Specifies the maximum number of concurrent reports in the queue, which must be less than or
equal to the number that the license permits. For details, see Appendix 1: Properties in the server.
properties file.
Advanced
Installing silently
JReport provides two files for installing JReport Server silently without user participation in the
installation process. It is ServerInstall_typical.properties for the Typical Installation for Standalone
Server type and ServerInstall_custom.properties for the Custom Installation for Standalone Server
type.
Follow the steps below to install JReport Server silently:
1. Download the appropriate file from the Jinfonet website according to your requirement.
2. Some built-in demo reports (\SampleReports\*.cls) with Derby as the data source (install_root\db
\SampleDB.script) have been provided. At the end of the installation, the installer will configure
the reports and catalog to the correct data path. This calls some AWT classes that require GUI
support.
So, if you have an X server installed, you should set the Display variable so that this step can be
performed successfully.
$ DISPLAY=hostname(or IP address):0.0
$ export DISPLAY
Note: If you do not have X server or a pure text environment, this step can be ignored.
However, you may find that the demo reports will not be able to run after you start the
JReport Server due to having the wrong default data source path. In this case, you can use
JReport Designer to publish some working reports for testing purposes.
3. Run the following command, and JReport Server will be installed in the designated path:
$ ./jrserver-xxx-linux.bin -i silent -f ServerInstall_typical.properties (change
jrserver-xxx-linux.bin to the real file name of the installation file)
Notes:
●
●
When installing JReport Server silently, make sure you do not use overwrite installation, instead,
install the server to a new directory.
When you install the Update or Service Pack silently, edit the file update.properties in
<install_root>\help\samples\SilentInstall to your own requirements. This file is used to
create an option file (i.e. response file) for the Installation Wizard. It predefines all the information
that is required for the installation.
You can also create a property file and save it as follows:
USER_INSTALL_DIR=/usr/local/JReport/Server
USER_KEY=UID
USER_PASSWORD=Password
Modify the above lines according to your own environment and configurations.
Installing using the console interface
JReport enables you to perform an interactive installation from a command prompt on platforms that
do not have GUI. In this way, you are able to see the installation status and follow the installation
process.
Take the following steps to perform console installation:
1. Download the appropriate installation file according to your system reuqirement from the Jinfonet
download center: http://www.jinfonet.com/downloadjreport/.
2. Run the following command:
For Unix and z/Linux:
$ chmod +x jrserver-xxx-linux.bin
$ ./jrserver-xxx-linux.bin -i console (change jrserver-xxx-linux.bin to the real file name of
the installation file)
For Windows:
jrserver-xxx-windows.exe -i console (change jrserver-xxx-windows.exe to the real file name
of the installation file)
3. Make decisions following the installation process.
Installing on Unix manually
In some rare cases, JReport Server may fail to install on Unix directly. In this case, follow the steps
below to install it manually:
1. Install JReport Server on Windows following the steps in Installing on Windows, but don't start it.
2. Prepare a directory on Unix where you will copy the installation, for example /opt/JReport/
Server.
3. Modify javahome and reporthome in the following files in <install_root>\bin to the Unix
directories where the Java JDK is located and the directory you are going to copy the release to,
using absolute path. Be sure to modify them carefully. Any mistake will cause problems starting
JReport.
report.ini
servlet.properties
setenv.sh
4. Modify javahome in the file env.sh in <install_root>\derby\bin to the Unix directory where the
Java JDK is located, using absolute path.
5. Delete the file server.properties from <install_root>\bin if it exists and remember to reset the
required configuration settings on the JReport Administration page (8889 as the default port) after
launching JReport Server on Unix. The server.properties file is created if you use the custom
format to install.
6. Make a zip or jar archive of the above folders, and then copy it to your Unix system (use binary
format if using FTP).
7. Extract the folder in the destination directory in accordance with the path defined in the property
files.
8. Use the dos2unix command to convert all the .sh files under <install_root>/bin to the format
that can be recognized by Unix. You can execute the command like this:
$ dos2unix *.sh
9. Use the chmod command to set the converted files under <install_root>/bin to have read, write
and execute permission. You can execute the command like this:
$ chmod 777 *.sh
10. Start a shell (Console) and login as root or become the root user by running the su command.
Make JRServer.sh executable and then start JReport Server by running ./JRServer.sh.
Note: If you fail to intall JReport Server on your z/Linux system directly, you can also follow the above
steps to install the server manually.
Installing by building a war file on Windows to deploy
to Linux/Unix
There are user cases when they need to install JReport Server into application servers in the cloud and
may not even own a machine of the type they are installing to. For example you use Tomcat on Linux
in a cloud environment but only have Windows machines available locally. You can then install JReport
server on Windows, make a war file and then deploy it to the Tomcat on Linux.
1. Install JReport Server on the local Windows machine.
2. Create a WAR via the following command line while specifying a report home. The report home
uses the path on Linux on the target machine.
makewar.bat -Dreporthome=/opt/reporthome
3. Add any JDBC drivers that are required into the jreport.war/WEB-INF/lib directory.
4. Visit Tomcat from the local machine by the URL http://<host>:8080/, deploy the WAR. 8080 is
the default port of Tomcat and suppose it works.
5. Log onto JReport Server Administration console by the URL http://<host>:8080/jreport/admin,
go to the Data tab on the system toolbar, configure the server database for System DB/realm DB/
Profiling DB. It shouldn't be Derby.
6. Restart JReport Server and access http://<host>:8080/jreport to see if you can run reports.
Uninstalling JReport Server
Use either of the following methods to remove JReport Server:
●
●
From the Control Panel, open Add or Remove Programs, and then select JReport Server 13 to
uninstall it.
Run uninstaller.exe (uninstaller on Unix) in <install_root>\_uninst.
Note: The uninstaller will remove all the files generated by the installer, while the files that are created
later by the program will be retained. They should be removed manually.
Solving installation problems
This section is trying to help you solve the problems you encounter during the installation.
Where to find log information
If error occurs during the installation, you can check the log information recorded to find out what the
problem is. Where logs are generated depends on when the installation process get stuck:
If the installation is cancelled before you click the Install button on the installation wizard, logs are
created on the desktop for Windows and in the userhome directory for Unix/Linux.
●
If the installation is cancelled after you click the Install button on the installation wizard, logs are
created in the logs folder in the installation root directory.
●
Besides, on a Windows platform, you can choose to specify the log destination that should use absolute
path and log file name when launching the installation wizard by running the following command:
jrserver-xxx-windows.exe -D$INSTALL_LOG_NAME$="Install.log" -D$INSTALL_LOG_DESTINATION
$="D:\temp"
or
$ ./jrserver-xxx-linux.bin -D$INSTALL_LOG_NAME$="Install.log" -D$INSTALL_LOG_DESTINATION
$="/opt/temp"
Change jrserver-xxx-windows.exe or jrserver-xxx-linux.bin to the real file name of the installation file.
Feel free to send your questions to [email protected]
An issue on Windows Vista
Problem
When running JReport Server's installer on Windows Vista, the installer cannot find the installed JDKs.
Reason
By default Vista's security settings are stricter than Windows 2000, XP, and 2003. The children
processes do not inherit the execution right from their parent process.
Solution
Make the compatibility property of the installer file (.exe) available:
1. Right-click the installer file, and select Properties from the shortcut menu.
2. In the Compatibility mode panel of the Compatibility tab, check the Run this program in
compatibility mode for option, and then select Windows 2000 from the drop-down list.
3. Click OK.
4. Run the installer.
JReport Server reporthome directory overview
This section provides a general view of the directories in the JReport Server installation root, including
what they contain, what they are used for, and how to set their location if possible.
The following is a list of the server reporthome directories:
Directory
Contents
Directory location Configurability
_uninst
Files used for uninstalling the JReport
Server.
Fixed.
bin
Command, configuration, and
properties files.
Fixed.
db
Demo reports' database.
Fixed.
Demo
Demo reports used in the tutorial
lessons.
Fixed.
derby
The Derby program and database
resources.
Fixed.
dynamicclasses
UDS jar/zip files.
The directory location can be specified by
the server.dynamic.class.dir property in
the server.properties file in
<install_root>\bin.
font
TTF font.
The directory location can be specified by
-Djreport.server.font.path or by the
server.font.path property in the server.
properties file in <install_root>\bin.
gisinfo
Report related Geographic Information Fixed.
files.
help
Help documents introducing the
function, features and usage of
JReport Server and JReport Designer
together with Tutorial manual.
Fixed.
history
Version files.
The directory location can be specified by
the servlet.jrserver.initArgs property in
the servlet.properties file in
<install_root>\bin.
images
Public images for Page Report Studio.
Fixed.
jreports
Demo reports.
Fixed.
When scheduling a task to disk, the
directory refers to the destination root
of the server resource tree.
lib
Library files required by JReport
runtime.
Fixed.
logs
Log files.
The directory is the default location for
log files.
ntservice
Files for C program and for writing a
Windows NT-service to run JReport
Server.
Fixed.
portlet
Resources for building portlet wars.
Fixed.
prestart
Reads customized configuration for
launching JReport Console and
Administration pages from the Start
menu.
Fixed.
profiling
Profiling related files.
Fixed.
properties
Default location for JReport Server
realm database.
The directory location can be specified
using the URL option on the JReport
Administration page > Data > Realm DB
> Configuration tab.
public_html
Standalone web app folder.
Fixed.
realm
Realm files.
Fixed.
resources
Language packages for specifying
JReport Server UI language.
Fixed.
scratchdir
Output files of compiled JSPs.
The directory location can be specified by
the servlet.jspservlet.initArgs property in
the servlet.properties file in
<install_root>\bin.
script_files
Script files for creating and deleting
system database tables.
Fixed.
style
CSS style files and style group files.
The directory location can be specified by
stylePath in the report.ini file in
<install_root>\bin.
temp
Engine temp files and Server temp
result files.
For Engine temp files, the directory
location can be specified by tempPath in
the report.ini file in <install_root>\bin.
Fixed for Server temp result files.
templates
Templates for web reports.
Fixed.
txtdriver
Demo reports' flat data files.
Optional.
Upgrading JReport Server
Upgrading a standalone JReport Server and an integrated JReport Server involves different processes
while sharing some common steps. Both updated JReport Servers require converting the report
resources in the old version in order to comply with the new server version.
Before upgrading, the old version JReport Server should be shut down.
Upgrading in a standalone environment
JReport Server 12 provides two migration tools in <install_root>\bin folder, which can help you to
convert all the resources on the previous version of JReport Server before version 6.0. Resources the
migration tools cover include the security information (realm, user, group, protection, and ACL), report
resources (catalog and reports), scheduled tables, completed tables, version and version tables, and
other relevant information (such as fonts, NLS, and style groups).
Note: When installing the JReport Server 12 into the same directory as the old version, the report level
resources in the old version will be maintained and not be replaced by the report resources of V12.
Upgrading a version later than V6.0 (included) to V12
To upgrade a version later than V6.0 (included) to V12, take the steps below. Here is a case showing
you how to upgrade V11.1 to V12, provided that the old JReport Server is located in C:\JReport
\Server11.1.
1. Backup the file dbconfig.xml in C:\JReport\Server11.1\bin folder.
2. Check the value of property derby.drda.portNumber in C:\JReport\Server11.1\derby\derby.
properties if derby is in use and remember it.
3. Install JReport Server 12 to C:\JReport\Server11.1. In the Choose Installation Set screen,
choose Typical Installation for Standalone Server. In the System Database screen, check the Trial
Database radio button, and set the port number same as the port number mentioned in step 2.
4. After the installation is complete, restore the file dbconfig.xml we backed up in step 1. Then start
JReport Server to check the upgraded version.
Upgrading a version between V5.2 Build 590 (included) and V6
(excluded) to V12
You can make the upgrade using the migration tool MigrationV52.bat (MigrationV52.sh for Unix) that is
available in the <install_root>\bin folder. This tool is used to convert all the resources of the
versions between V5.2 Build 590 (included) and V6 (excluded) to the resources of JReport Server 12. If
you install the new version to the same folder as the old one, the parameter can be omitted.
●
Usage
MigrationV52 [orgReportHome]
Options
●
❍
orgReporthome
The reporthome of the original JReport Server. If this parameter is not provided, the reporthome of
JReport Server 12 will be used as its value.
Case 1: Installing JReport Server 12 to a new folder (recommended)
1. Provided that the old JReport Server is located in C:\JREntServer595. Install JReport Server 12 to
a new folder C:\JReport\ServerV12. DO NOT start the newly installed JReport Server.
2. In the DOS window, switch to <install_root>\bin, and run MigrationV52 C:\JREntServer595.
Case 2: Installing JReport Server 12 to the folder where the old version resides
1. Provided that the old JReport Server is located in C:\JREntServer595. Install JReport Server 12 to
the same location. DO NOT start the newly installed JReport Server.
2. In the DOS window, switch to <install_root>\bin, and run MigrationV52.bat.
Upgrading a version earlier than V5.2 Build 590 (excluded) to V12
You can do the upgrade using the migration tool MigrationBV52.bat (MigrationBV52.sh for Unix) that is
available in the <install_root>\bin folder. This tool is used to convert all the resources of versions
lower than V5.2 Build 590 to the resources of JReport Server 12. If you install the new version to the
same folder as the old one, the parameter can be omitted.
●
Usage
MigrationBV52 [orgReportHome]
Options
●
❍
orgReporthome
The reporthome of the original JReport Server. If the parameter is not provided, the reporthome of
JReport Server 12 will be used as its value.
Case 1: Installing JReport Server 12 to a new folder (recommended)
1. Provided that the old JReport Server is located in C:\JREntServer580. Install JReport Server 12 to
a new folder C:\JReport\ServerV12. DO NOT start the newly installed JReport Server.
2. In the DOS window, switch to <install_root>\bin, and run MigrationBV52 C:\JREntServer580.
Case 2: Installing JReport Server 12 to the folder where the old version resides
1. Provided that the old JReport Server is located in C:\JREntServer580. Install JReport Server 12 to
the same location. DO NOT start the newly installed JReport Server.
2. In the DOS window, switch to <install_root>\bin, and run MigrationBV52.bat.
Upgrading in an integration environment
1. Suppose that you already have a standalone JReport Server 12, whether it is installed directly or
upgraded from a previous version. In this step you need not convert the old version reports.
2. Use the JReport Server 12 to create a self-contained WAR/EAR file. For information on how to
create the WAR/EAR, see Building a WAR/EAR file to include a self-contained JReport Server.
Remember that when building the jreport.war file in a standalone JReport Server 12, the
ReportHome of jreport.war must be the same as that of the jreport.war in the previous version.
3. Use the Java application server that integrates the previous version of JReport Server to deploy
the new self-contained WAR/EAR and update the old WAR/EAR with the new one.
By now, if the previous version of JReport Server is later than V6.0 (included), the integrated
JReport Server has already been upgraded to V12. But if the previous version is earlier than V6.0,
go to step 4 and you need do further upgrade.
4. For a previous version between V5.2 Build 590 (included) and V6 (excluded): in the DOS window,
switch to <reporthome>\bin, and run MigrationV52.bat.
For a previous version earlier than V5.2 Build 590 (excluded): in the DOS window, switch to
<reporthome>\bin, and run MigrationBV52.bat.
Launching JReport Server
After you have installed JReport Server, you must set up the reporting environment and start it before
you can access it via a web browser. This chapter provides you with detailed information of how to run
JReport Server in different running modes.
The following topics are discussed in this chapter:
●
Setting up the reporting environment
●
Running as a standalone server
●
Running as an OS service
●
Running within an application server
Setting up the reporting environment
Now that you have installed JReport Server, you can start it. However, it is better to first check the
reporting environment to see whether you have published the reports including the catalog files, added
the necessary class paths, and set up the data sources.
Report publishment & creation
The separation of the report file and the data is powerful. It facilitates easy re-use of the report's
layout. Report files built with JReport Designer can then be published to JReport Server for running in
the thin-client/server mode. Today, computing is a service-based model in which web based
applications are rapidly replacing monolithic fat-client hosted and maintained software applications.
JReport Server is a high performance server for running reports on demand or unattended on a
scheduled basis. In this environment, thousands of clients may view, print and generate new reports.
JReport Server has its own resource tree with each node mapping to a folder or file in your physical
drive. So when publishing report files to the server, it is recommended that you check:
●
Whether the report files reside somewhere in the server machine.
●
Whether the files are mapped in the resource tree.
●
That not only the report files, but also the catalog files (including the .fml file) exist and are in the
same directory. In addition, one directory can only contain one catalog. However, it can contain
many report files which use that catalog.
Data sources
You may have your own catalogs and reports that you developed, and want them to be run and be
distributed by JReport Server. In order to do this, the data sources used by your catalogs must be
correctly set to the runtime environment of JReport Server.
User data source
Append the class path of your user class files to the first item of the classpath set in your batch file or
command line that starts JReport Server. If you are using JReport Server embedded in an application
server, add your user class files to the WAR file used to deploy JReport Server.
Additional class paths
If your reports reference any external classes, you will need to add them to the classpath option in the
batch file and command line that starts JReport Server. For example, if your reports contain user
defined objects (UDO) or user defined formula functions, do not forget to add them to the class path or
to the WAR file.
Running as a standalone server
JReport Server can be started from the web application server contained in the JReport Server
package. This section explains how to start JReport Server as a standalone report server, how to send
commands to the server and how to use the batch files in the <install_root>\bin directory.
●
Starting using launch files
●
Starting using Java
●
Sending commands to JReport Server from Java
●
Running without a GUI
Starting using launch files
After you have installed JReport Server, many batch files are automatically generated in
<install_root>\bin. They are for assisting you with using and maintaining JReport Server. All of
these batch files can be edited to suit different circumstances. However, make sure that you
understand their functions when you want to edit them.
The following are the JReport Server launch files.
browser.bat
This tool detects the default client browser and installation path. It is invoked by launchpad.bat.
CmdSender.bat/CmdSender.sh
This tool is for sending commands to JReport Server. If the option "-s" or "-p" is not used, the JVM
system property "reporthome" must be defined so that CmdSender.bat/CmdSender.sh will use it to get
data from the local machine.
Usage
cmdsender [-s:<server> -p:<port> -u:<user>] -w:<password> shutdown|localshutdown|(local:on|off)
Options
●
●
●
●
●
●
●
●
-s
The server host name.
-p
The administration port.
-u
The admin user name.
-w
The admin password.
shutdown
Shuts down the server.
localshutdown
Shuts down the local server.
local
The administration tasks are available to local host only.
gc
Run the Java garbage collector.
DBMaintain.bat/DBMaintain.sh
This tool is for administrators to back up and restore JReport Server data. It is invoked by the following
command line:
Usage
DBMaintain -[?|cleanup|B<[systemtables|realmtables|profiling]:<filename>>|R<[systemtables|
realmtables|profiling]:<filename>>]
Options
●
●
●
-?
Displays the usage information and then exits.
-cleanup
Checks integrality of the server data and cleans up the invalid data.
-Bsystemtables:<filename>/-Brealmtables:<filename>/-Bprofiling:<filename>
Backs up the data in the database with the related data to a specified file.
For example, for backing up the server data realmtables to file c:\jsback.dat, you can type:
DBMaintain -Brealmtables:c:\jsback.dat
●
●
-B0realmtables:<filename>
Only backs up the data in the realm database.
-Rsystemtables:<filename>/-Rrealmtables:<filename>/-Rprofiling:<filename>
Restores the data including the related data outside the database from a specified file.
For example, for restoring server data realmtables from the file c:\jsback.dat, you can type:
DBMaintain -Rrealmtables:c:\jsback.dat
●
-R0realmtables:<filename>
Only restores the data in the realm database.
DJRServer.bat/DJRServer.sh
This tool is used to launch JReport Server with debug and log information. The output log files are in
the <install_root>\logs directory. In case of problems, you may run this batch to reproduce the
problem. Open the files to see the detail information and find out the problem. Send the log files to
[email protected] if you are unable to resolve the problem.
Usage
DJRServer [-?|-p <port>|-ap <adminport>|-realm <realmname>|-l backlog|-m <max>
|-t <timeout>|-s <filename>|-web <directory>|-env|-silent|
|-local|-vDebug|-vError|-jrs.admin.server <host:port>|-cleanup]
Options
●
●
●
-?
Prints this help message.
-p <port>
The port number to listen on.
-ap <adminport>
The port number which is used by the administration tools.
●
●
●
●
●
●
●
●
●
●
●
●
●
-realm <realmname>
Specifies the active realm.
-l <backlog>
The maximum queue length for incoming connections.
-m <max>
The maximum number of connection handlers.
-t <timeout>
The connection timeout in milliseconds.
-s <filename>
The servlet property file name. If this option is not used, the file servlet.properties in <install_root>
\bin will be used as the servlet property file when launching JReport Server.
-web <directory>
The root directory when accessing the server via the web. Its default value is <intall_root>
\public_html.
-env
Prints the environment.
-silent
No output is sent to the console.
-local
The administration tasks are available on local host only.
-vDebug
Enables JReport Engine to output messages to a file and sets all log files' trace levels to INFO and
error levels to WARN.
-vError
Enables JReport Engine to output messages to a file and sets all log files' trace levels to OFF and
error levels to ERROR.
-jrs.admin.server <host:port>
The admin server host and RMI port.
-cleanup
Checks integrality of the server data and cleans up the invalid data.
JRServer.bat/JRServer.sh
This tool is used to launch JReport Server in standalone mode without any predefined options.
On Windows, you can start server by double-clicking on JRServer.bat. If you cannot start the server
successfully in this way, the reason will be displayed in the MS-DOS command prompt.
Usage
JRServer [-?|-p <port>|-ap <adminport>|-realm <realmname>|-l backlog|-m <max>
|-t <timeout>|-s <filename>|-web <directory>|-env|-silent|
|-local|-vDebug|-vError|-logall|-jrs.admin.server <host:port>|-cleanup]
Options
●
●
●
●
●
●
●
●
●
●
●
●
●
●
●
●
●
●
-?
Prints this help message.
-p <port>
The port number to listen on.
-ap <adminport>
The port number which is used by the administration tools.
-realm <realmname>
Specifies the active realm.
-l <backlog>
The maximum queue length for incoming connections.
-m <max>
The maximum number of connection handlers.
-t <timeout>
The connection timeout in milliseconds.
-s <filename>
The servlet property file name. If this option is not used, the file servlet.properties in <install_root>
\bin will be used as the servlet property file when launching JReport Server.
-web <directory>
The root directory when accessing the server via the web. Its default value is <intall_root>
\public_html.
-env
Prints the environment.
-silent
No output to the console.
-local
The administration tasks are available on local host only.
-vDebug
Enables JReport Engine to output messages to a file and sets all log files' trace levels to INFO and
error levels to WARN.
-vError
Enables JReport Engine to output messages to a file and sets all log files' trace levels to OFF and
error levels to ERROR.
-log[:file Name] (deprecated)
Outputs JReport Engine messages to the log file as specified and uses the -vDebug level.
-logall
Sets all loggers' trace level to INFO and error level to WARN.
-jrs.admin.server <host:port>
The admin server host and RMI port.
-cleanup
Checks integrality of the server data and cleans up the invalid data.
Notes:
●
●
You may need to set an appropriate -Dfile.encoding option in the file to start JReport Server in order
to view characters correctly.
You may also need to set an appropriate -Dresolution option in the file to start JReport Server in
order to set the system resolution in DPI.
jrenv.bat/jrenv.sh
This tool is for generating the report environment file report.env in the current directory. This file can
help the Jinfonet support staff assist you when you run into problems.
launchpad.bat
This tool is used to launch JReport Server in the standalone mode and open the JReport Server Launch
Pad page.
makewar.bat/makewar.sh
See here.
MigrationBV52.bat/MigrationBV52.sh
This tool is used to convert all the resources from JReport versions which are lower than V5.2 Build 590
to the resources of JReport Server V8. If you install the new version to the same folder as the old one,
the parameter can be omitted.
Usage
MigrationBV52 [orgReportHome]
Options
●
orgReporthome
The reporthome of the original JReport Server. If this parameter is not provided, the value of
"reporthome" of new JReport Server will be used as its value.
MigrationV52.bat/MigrationV52.sh
This tool is used to convert all the resources of which the versions are between V5.2 Build 590
(included) and V6 (not included) to the resources of JReport Server V8. If you install the new version to
the same folder as the old one, the parameter can be omitted.
Usage
MigrationV52 [orgReportHome]
Options
●
orgReporthome
The reporthome of the original JReport Server. If this parameter is not provided, the value of
"reporthome" of new JReport Server will be used as its value.
NJRServer.bat/NJRServer.sh
This tool is used to launch JReport Server without JIT option. If your server often crashes with JIT
option, try this batch file instead of JRServer.bat.
Usage
NJRServer [-?|-p <port>|-ap <adminport>|-realm <realmname>|-l backlog|-m <max>
|-t <timeout>|-s <filename>|-web <directory>|-env|-silent|
|-local|-vDebug|-vError|-logall|-jrs.admin.server <host:port>|-cleanup]
Options
●
●
●
●
●
●
●
●
●
●
●
●
●
-?
Prints this help message.
-p <port>
The port number to listen on.
-ap <adminport>
The port number which is used by the administration tools.
-realm <realmname>
Specifies the active realm.
-l <backlog>
The maximum queue length for incoming connections.
-m <max>
The maximum number of connection handlers.
-t <timeout>
The connection timeout in milliseconds.
-s <filename>
The servlet property file name. If this option is not used, the file servlet.properties in <install_root>
\bin will be used as the servlet property file when launching JReport Server.
-web <directory>
The root directory when accessing the server via the web. Its default value is <intall_root>
\public_html.
-env
Prints the environment.
-silent
No output to the console.
-local
The administration tasks are available on local host only.
-vDebug
Enables JReport Engine to output messages to a file and sets all log files' trace levels to INFO and
error levels to WARN.
●
●
●
●
●
-vError
Enables JReport Engine to output messages to a file and sets all log files' trace levels to OFF and
error levels to ERROR.
-log[:file Name] (deprecated)
Outputs JReport Engine messages to the log file as specified and uses the -vDebug level.
-logall
Sets all loggers' trace level to INFO and error level to WARN.
-jrs.admin.server <host:port>
The admin server host and RMI port.
-cleanup
Checks integrality of the server data and cleans up the invalid data.
register.bat
It is invoked by browser.bat.
RMIAuthFileCreator.bat/RMIAuthFileCreator.sh
This tool is used to generate the rmi authentication file. JReport Server uses the authentication file to
secure remote objects. If no argument was provided, an authentication file named "rmi.auth" will be
created in <install_root>\bin, using the user ID and install key of JReport Server.
Usage
RMIAuthFileCreator [authFileName [userid key]]
Options
●
●
●
●
?
Shows the usage message.
authFileName
The RMI authentication file name. If only input this argument, the user ID and install key of JReport
Server will be used to create the authentication file.
userid
The user ID, which will be used to generate the contents of the authentication file.
key
The key which will be used to generate contents of the authentication file.
rp.bat/rp.sh
This tool is for replacing user ID and license key.
Usage
rp UID Key
rptconv.bat/rptconv.sh
This tool is for converting old report schema to be current version.
Usage
rptconv "-source=source_path" ["-target=destination_path"] [-r] [-s]
Options
●
●
●
-source
Specify the source path of the reports that are to be converted.
-target
Specify the destination path for the converted reports.
-r
Replace the source report with the converted version.
If this option is set, ["-target=destination_path"] is ignored.
If both "-r" and "-target" are not specified, the converted reports are saved in the same directory as
the source reports and named as "converted_SourceReportName".
●
-s
Convert all the reports in the specified directory, including the reports in all subdirectories.
Examples
●
To convert a single report:
rptconv "-source=C:\JReport\Server\jreports\SampleReports\InvoiceReport.cls" "–
target=C:\temp"
This will convert C:\JReport\Server\jreports\SampleReports\InvoiceReport.cls to C:\temp
\InvoiceReport.cls.
rptconv "-source=C:\JReport\Server\jreports\SampleReports\InvoiceReport.cls" "–
target=C:\temp\1.cls.xml"
This will convert C:\JReport\Server\jreports\SampleReports\InvoiceReport.cls, save the converted
report to C:\temp, and name it as "1.cls.xml" (if license allows).
rptconv "-source=C:\JReport\Server\jreports\SampleReports\InvoiceReport.cls"
This will convert C:\JReport\Server\jreports\SampleReports\InvoiceReport.cls, save the converted
report in the same directory, and name it as "converted_InvoiceReport.cls".
rptconv "-source=C:\JReport\Server\jreports\SampleReports\InvoiceReport.cls" -r
This will overwrite C:\JReport\Server\jreports\SampleReportss\InvoiceReport.cls.
●
To convert all reports (*.cls, *.rpt, *.clx, *.cls.xml) in a directory:
rptconv "-source=C:\JReport\Server\jreports" "–target=C:\temp"
This will convert all the reports in C:\JReport\Server\jreports and save the converted reports to C:
\temp. The converted reports use the same file names as source reports.
rptconv "-source=C:\JReport\Server\jreports" "–target=C:\temp" -s
This will convert all the reports in C:\JReport\Server\jreports and in the subdirectories and save the
converted reports to C:\temp. The converted reports take the same file names and directory
structure as source reports.
rptconv "-source=C:\JReport\Server\jreports" "–target=C:\temp\*.cls" -s
This will convert all the reports in C:\JReport\Server\jreports and in the subdirectories and save the
converted reports to C:\temp. The converted reports take the same directory structure as source
reports and the suffixes of their file names are all changed to ".cls".
rptconv "-source=C:\JReport\Server\jreports" -r -s
This will convert all the reports in C:\JReport\Server\jreports and in the subdirectories. The
converted reports overwrite the source reports.
rptconv "-source=C:\JReport\Server\jreports"
This will convert all the reports in C:\JReport\Server\jreports. All the converted reports are saved in
the same directory and named as "converted_SourceReportName".
●
To convert a type of reports with same suffixes in a directory:
The usage is similar to converting a directory. You can specify the wildcard to filter reports, for
example:
rptconv "-source=C:\JReport\Server\jreports\SampleReports\*.cls" "–target=C:\temp"
This will convert all the reports with the suffix ".cls" in C:\JReport\Server\jreports
\SampleReports and save the converted reports to C:\temp.
Notes:
●
●
There must be one and only one catalog file in the directory where the reports to be converted
reside.
If the reports to be converted contain UDO or UDF, make sure the corresponding classes or jars are
included in the class path of rptconv.bat/rptconv.sh.
startAdministration.bat
This tool is used to launch the JReport Administration page from the Start menu after the server is
started.
startConsole.bat
This tool is used to launch the JReport Console page from the Start menu after the server is started.
stopServer.bat
This tool is used to exit JReport Server from the Start menu.
stopServer.sh
This tool is used to exit JReport Server.
Starting using Java
The class of the standalone server is jet.server.JREntServer. You can start JReport Server with the
following command instead of using the generated batch files:
JAVA -classpath <classpath> -Djava.compiler=NONE -Dreporthome=<install_root> jet.server.
JREntServer [options]
●
●
●
●
●
●
●
-classpath
The classpath must include the following packages originally in your <install_root>\lib:
JRESServlets.jar; JREntServer.jar; JREngine.jar; servlet.jar; log4j-1.2.8.jar;
-Djava.compiler=NONE
This is without JIT. This is not a required option. However, if you encounter problems running the
server and you think that they relate to the Java VM, you can try turning off the JIT compiler and
then running again.
-Djreport.url.encoding
Specifies the encoding to encode/decode escape characters in URL strings. If not specified, the
system default encoding will be used. For example: java ... -Djreport.url.encoding=8859-1...
-Dreporthome
This is where JReport Server is installed. It is the Destination Location you specified when you
installed it. This option is required. When you set the reporthome, upon launching, JReport will try to
find the jslc.dat and report.ini files in <install_root>\bin and check whether they are valid. Jslc.dat
is the License control file. Open report.ini, and you will find the configuration information, including
the temp, template and the help path. JReport will use the temp path to export the temporary files
so you should make sure that the temp folder specified in report.ini exists and has space available.
-Dfile.encoding
Specifies the encoding to encode/decode escape characters in the server data. If not specified, the
system default encoding will be used. For example: java ... -Dfile.encoding=8859-1...
-Dresolution
Sets the system resolution in DPI. If not specified, the system default resolution will be used, which
is the resolution of your monitor, for example, -Dresolution=96.
[options]
Option
Description
-?
Print brief help message.
-p port
The port that this server listens on, default is 8888.
-ap adminport
The port number that the remote administration uses, default is 8889.
-l backlog
Maximum length of queue for incoming connection indications.
-m max
Maximum number of connection handlers.
-t timeout
Connection timeout in milliseconds.
-s filename
Servlet property file name.
-realm realmname
Active realm when the server starts up.
The specified realm should exist, otherwise the server will use an existing
realm as the active realm. The server will then record a warning message in
the log file, and set the selected active realm by the server.realm.active
property in the server.properties file.
-web directory
Web application server root directory, default is <intall_root>
\public_html.
-local
Administration on local host only.
-vDebug
Enables JReport Engine to output messages to a file and sets engine log file's
trace level to INFO and error level to WARN.
-vError
Enables JReport Engine to output messages to a file and sets engine log file's
trace level to OFF and error level to ERROR.
-env
Print environment settings when the server starts up.
-silent
Outputs nothing, not even the server start information.
-log[:file Name]
(deprecated)
Outputs JReport Engine messages to the log file as specified and uses the vDebug level.
-logall
Sets all loggers' trace level to INFO and error level to WARN.
-jrs.admin.server
host:port
The admin server host and RMI port.
-cleanup
Checks integrality of the server data and cleans up the invalid data.
Notes:
●
●
For detailed information on how to configure the logging and debugging information, read the
LogConfig.properties file in <install_root>\bin.
Some of the common options will be used in later chapters. In addition, JReport has automatically
generated some batch files for you so that you do not have to write a complicated command line.
You can find these in the <install_root>\bin directory.
Sending commands to JReport Server from Java
After JReport Server has been started as a standalone server, you can send commands to the server to
either shut it down or pop up the user interactive interface for administration. All of these can be done
through the class jet.server.CommandSender. The full command is as follows:
JAVA -classpath <classpath> -Djava.compiler=NONE [-Dreporthome=<install_root>] jet.
server.CommandSender [-s:server -p:port] -w:password [-?]|admin|shutdown|gc|(local:on|
off)
●
●
●
●
●
●
●
●
●
●
●
●
-?
Prints brief help message.
-Djava.compiler=NONE
This is without JIT. This is not a required option. However, if you encounter problems running the
server and you think that they relate to the Java VM, you can try turning off the JIT compiler and
running again.
-Dreporthome
This is where JReport Server is installed. It is the destination location you specified when you
installed it. It is required only if you do not execute the command from the local host on which
JReport Server is running.
-Dpoperror=true
This property is used to control whether to pop up a message to show error information. The default
value is false which indicates that the error message will not be displayed.
-Classpath
The classpath must include the following packages originally in your <install_root>\lib:
JRESServlets.jar; JREntServer.jar.
-s:server
Host name on which JReport Server is running.
-p:port
The port JReport Server used for administration. The default value is 8889.
-w:password
Password of the admin user. Example: -w:admin.
admin
A command sent to the server asking to pop up the user interactive interface for administering
JReport Server.
shutdown
A command sent to the server asking it to shut down.
local:on
A command sent to the server asking to only allow the administration commands sent by the local
machine.
local:off
A command sent to the server asking to accept administration commands from anywhere.
●
gc
A command sent to the server asking the JVM to schedule the Java Garbage Collector.
Note: Some of the common options will be used in the later chapters. In addition, JReport has
automatically generated the batch file CmdSender.bat for you so that you do not have to write a
complicated command line.
Running without a GUI
Many environments, such as mainframe machines and dedicated servers, do not support a display,
keyboard, or mouse. JReport Server supports Java headless implementation, in which case you do not
have to install a third-party tool, such as PJA, XWindows, or XVFB, in order to run JReport in a non-GUI
environment.
Using Java headless implementation
JReport Server runs fluently in headless environments. What you need to do is make some simple
configuration changes before starting JReport Server in headless environments.
To launch JReport Server in a headless environment:
1. Add -Djava.awt.headless=true as a JVM parameter before starting JReport Server.
2. Start JReport Server.
Note: If JDK 6 is used, it is not necessary to add the parameter -Djava.awt.headless manually,
because JDK 6 can automatically give a value to the parameter according to the environment the
server will run. For example, if it is headless, the true value will be given.
Using a third-party tool (deprecated)
The method of using a third-party tool is no longer needed but is still available in this release. It may
be removed in the future. The following introduces three ways to run JReport Server on Unix without
GUI.
Running with XVFB
XVFB is an acronym of the Xserver Virtual Frame Buffer. It can provide a virtual Xserver and release
you from the need of a real Xserver. It runs without a head or graphics card. XVFB is freeware and can
be obtained from x.org's X11R6 distribution. Compiling it is supposedly difficult, however, there are
some Solaris binaries on certain sites, including:
●
http://ferret.wrc.noaa.gov/Ferret/FAQ/graphics/Solaris_Xvfb.html
●
ftp.xfree86.org/pub/XFree86/3.3.6/binaries/Solaris
●
ftp.xfree86.org/pub/XFree86/4.0.1/binaries/Solaris
●
ftp.xfree86.org/pub/XFree86/4.0.1/binaries/Solaris-8
●
http://ferret.wrc.noaa.gov/Ferret/FAQ/graphics/Solaris_Xvfb.html
Take the following steps to run JReport Server with XVFB:
1. Install XVFB.
2. To have XVFB start up automatically when a workstation boots, you can add the Virtual Frame
Buffer to the Automatic Startup. That is, write a script /etc/init.d/xvfb as follows, and make it
executable.
#!/bin/sh
mode=$1
case "$mode" in
'start')
# start the X Virtual Framebuffer (Xvfb)
if [ -f /usr/X11R6/bin/Xvfb ]; then
echo "***Starting up the Virtual Frame Buffer on Screen 1***"
/usr/X11R6/bin/Xvfb :1 -screen 0 1152x900x8 &
fi
;;
*)
echo " Usage: "
echo " $0 start (start XVFB)"
echo " $0 stop (stop XVFB - not supported)"
exit 1
;;
esac
exit 0
Then create a soft link to /etc/rc2.d/S98xvfb:
ln -s /etc/init.d/xvfb /etc/rc2.d/S98xvfb
If you need not to start XVFB automatically, you can manually start up XVFB:
/usr/X11R6/bin/Xvfb :1 -screen 0 1152x900x8 &
3. Set DISPLAY to screen 1 (assuming that JReport Server is running on machine jaguar).
DISPLAY=jaguar:1.0
export DISPLAY
Then, you can start JReport Server. Logging out the terminal may result in JReport Server shutting
down. To avoid this, you can first start JReport Server in the background using the command nohup:
nohup ./JRServer &. This command will continue running programs specified by you and enables
JReport Server to ignore hangup signals.
Running with PJA toolkit
When there is neither X Window, nor XVFB available, a PJA (Pure Java AWT) Toolkit is supported to run
JReport Server. This is a Java library for drawing graphics developed by eTeks. It supplies a
replacement AWT toolkit and eliminates the requirement of an X display. To use it:
1. Install PJA. The PJA package is not included in our product, go to http://www.eteks.com/pja/en/
to download PJA and install it.
2. Install JReport Server.
3. Assuming that jrserver-xxx-linux.bin has been used to install JReport Server on a Non-GUI
platform, modify the file JRServer.sh in <install_root>\bin by appending /pja_2.4/lib/
pjatools.jar to the class path, and add the following options.
❍
-Xbootclasspath/a:pja.jar - (changing classpath is not enough).
❍
-Dawt.toolkit=com.eteks.awt.PJAToolkit - This enables the changing of AWT Toolkit.
❍
❍
❍
❍
-Djava.awt.graphicsenv=com.eteks.java2d.PJAGraphicsEnvironment - This enables the
changing of the Graphics environment.
-Djava2d.font.usePlatformFont=false - This avoids the class sun.java2d.loops.
RasterOutputManager calling the native method getPlatformFontVar(), which can cause a JVM
crash.
-Djava.awt.fonts=path - With path equal to the directory where the Lucida *.ttf files can be
found. You can add to the path other directories containing True Type Fonts by using a
separator.
Either -Duser.home=dir with dir equal to the directory where the sub directory lib containing
PJA font.properties file can be found, or add lib/font.properties to the user.home system
property.
Below is an example of the modified file JRServer.sh that is used to start up JReport Server:
#!/bin/sh
CLASSPATH=$REPORTHOME/lib/commons-net-ftp-2.0.0.jar:
$REPORTHOME/lib/sac.jar:$REPORTHOME/lib/servlet.jar:
$REPORTHOME/lib/ant.jar:$REPORTHOME/lib/jasper-compiler.jar:
$REPORTHOME/lib/jasper-runtime.jar:$REPORTHOME/lib/JREngine.jar:
$REPORTHOME/lib/JRESServlets.jar:$REPORTHOME/lib/JREntServer.jar:
$REPORTHOME/lib/maintain.jar:$REPORTHOME/lib/mail-1.4.jar:
$REPORTHOME/lib/activation-1.1.jar:$REPORTHOME/lib/JRWebDesign.jar:
$REPORTHOME/lib/itext_1.5.4.jar:$REPORTHOME/lib/poiHSSF_151.jar:
$REPORTHOME/lib/xercesImpl.jar:$REPORTHOME/lib/xml-apis.jar:
$REPORTHOME/lib/hsqldb.jar:$REPORTHOME/lib/tar.jar:
$REPORTHOME/lib/jai_core.jar:$REPORTHOME/lib/jai_codec.jar:
$REPORTHOME/lib/commons-codec-1.2.jar:$REPORTHOME/lib/log4j-1.2.8.jar:
$REPORTHOME/lib/jsch-0.1.30.jar:$REPORTHOME/derby/lib/derby.jar:
$REPORTHOME/derby/lib/derbyclient.jar:$REPORTHOME/derby/lib/derbynet.jar:
$REPORTHOME/derby/lib/derbytools.jar:$JAVAHOME/lib/tools.jar:$ADDCLASSPATH
cd $REPORTHOME/bin
$JAVAHOME/bin/java -Dawt.toolkit=com.eteks.awt.PJAToolkit
-Djava.awt.graphicsenv=com.eteks.java2d.PJAGraphicsEnvironment
-Djava2d.font.usePlatformFont=false
-Djava.awt.fonts=/usr/j2se/jre/lib/fonts:
/JREntServer/font:/usr/openwin/lib/X11/fonts/TrueType
-Dinstall.root=$REPORTHOME/ -Djreport.url.encoding=UTF-8 -Xmx512m
-Dreporthome=$REPORTHOME jet.server.JREntServer "[email protected]"
Notes:
●
●
Printing reports is not supported.
To support multiple encoding, the file charsets.jar in jre\lib should be added to -Xbootclasspath.
Without this Jar file, only the default encoding (iso8859-1) can be applied to JReport. For the
encoding types which are supported by charsets.jar, refer to the website http://java.sun.com/
j2se/1.4.2/docs/guide/intl/encoding.doc.html.
●
If you are using other True Type Fonts instead of the fonts in X11, you should add the location of the
Lucida*.ttf files directory to -Djava.awt.fonts.
Starting from a telnet session with an X server installed
If you are using telnet to start JReport and your Unix has an X server installed, you can directly point
your display to your X server:
$ DISPLAY=hostname(or IP address):0.0
$ export DISPLAY
Then, you can run JReport Server or your application with JReport embedded.
Running as an OS service
JReport Server can be configured as an OS service. This section shows you how to run JReport Server
as a service of Windows XP, Unix and Linux.
●
Running as a Windows Service
●
Running as a service on Unix
●
Running as a service on Linux
Running as a Windows Service
A tool is provided to assist you in installing JReport Server as a Windows Service. This tool JRservice.
exe can be found in <install_root>\bin.
You will get the following information if you run JRservice.exe without any options:
Usage:
JRService -install [-interactive] to install the service
JRService -remove
to remove the service
-interactive to enable JReport Server service
to interact with the desktop
StartServiceCtrlDispatcher being called.
This may take several seconds. Please wait.
●
●
●
JRService -install
Running JRservice.exe with the -install option will install JReport Server as a Windows Service. If you
open the Services item in the Control Panel, you will find a service named JReport Server in the list.
JRService -install -interactive
If you use the -interactive option together with -install, the service installed will be run in interactive
mode. That is, when you start the service, a Command Prompt Window will pop up. However, if you
don't specify this option when you install the service, the Command Prompt Window will not be
displayed on the window when you start the service. After you have installed JReport Server as a
service, you will then be prompted to re-start your computer for the service installation to take effect.
JRService -remove
Running JRservice.exe with -remove option removes the Windows service of JReport Server from
Windows. However, before you run this, you should stop the service.
Configuring JReport Server service
The parameters for the Windows service of JReport Server are read from the file NTService.ini in
<install_root>\bin.
In this file you will find three parameters specified, as shown in the following example:
JavaVM="C:\jdk1.6.0_17\jre\bin\java.exe"
StartArg= "-Dinstall.root=C:\JReport\Server"
-classpath "C:\JReport\Server\lib\JREntServer.jar;
C:\JReport\Server\lib\JREngine.jar;C:\JReport\Server\lib\servlet.jar;C:\TEMP"...
-Djava.compiler=NONE -Dreporthome=C:\JReport\Server jet.server.JREntServer
ShutdownArg= "-Dinstall.root=C:\JReport\Server"
-classpath "C:\JReport\Server\lib\JREntServer.jar;
C:\JReport\Server\lib\JREngine.jar;C:\JReport\Server\lib\servlet.jar;C:\TEMP" ...
-Djava.compiler=NONE
-Dreporthome=C:\JReport\Server jet.server.CommandSender localshutdown
●
●
●
JavaVM
The path of the Java VM.
StartArg
The Java command line for launching JReport Server as an independent web application server. This
will be called when the service is started.
ShutdownArg
The Java command line for shutting down JReport Server. This is called when the service is stopped.
Starting the service
There are two ways to start the JReport Server service.
●
●
After the server has been installed as a service, it is by default configured to start automatically each
time. In other words, without otherwise modifying the Control Panel, the service will start
automatically each time Windows is started.
You can directly start the service through the Services item in the Control Panel. Open the Services
list, find JReport Server on the list, select it and click the Start button.
You can change the options in the file NTService.ini in <install_root>\bin before you start the
service. In the example above, there are no options specified in StartArg. If you would like to set all
error log levels to WARN and trace log levels to INFO, you will need to append -logall at the end, as in
the following example:
...
StartArg= "-Dinstall.root=C:\JReport\Server"
-classpath "C:\JReport\Server\lib\JREntServer.jar;
C:\JReport\Server\lib\JREngine.jar;C:\JReport\Server\lib\servlet.jar;
C:\JReport\Server\lib\log4j-1.2.8.jar;C:\TEMP" -Djava.compiler=NONE
-Dreporthome=C:\JReport\Server jet.server.JREntServer -logall
...
Reference: For more information on the options available, see Starting JReport Server using Java.
Stopping the service
There are three ways for you to stop the JReport Server service:
●
●
●
Open the Control Panel, go to Administrative Tools, double-click the Services item, select
JReport Server, and then click the Stop button if it is not disabled.
Run the batch file CmdSender.bat in <install_root>\bin with the localshutdown argument, for
example: <install_root>\bin\CmdSender.bat localshutdown.
Use the Shut Down the Server button
on the JReport Administration page.
Notes:
●
●
All ODBC data sources used by the JReport Server Service belong to the System DSN. System data
sources can be used by all users on a computer, and are visible to all users on the computer and
system-wide services, such as Microsoft Windows services. User data sources can only be used by
the current user and are visible only to that user. To establish JReport Server as a service, you
should choose System Data Source. That is, define the data source in the System DSN. To do this,
open Data Source (ODBC) in Control Panel, and add the data source used by JReport Server to the
System DSN panel. Also, remove any old ones from the User DSN.
When using NT service to start JReport Server, the mapped disk in path cannot be accessed due to
JVM limitation. You should use UNC path (e.g. \\127.0.0.1\public_write) instead of the mapped disk
it is mapped to (e.g. Z).
Running as a service on Unix
Assuming that JReport Server has been installed to /user/report/jns,
1. Write a script /etc/init.d/jrserver as follows, and make it executable.
#!/bin/sh
mode=$1
if [ ! -d /user/report/jns ]
then # JReport not installed
exit 1
fi
case "$mode" in
'start')
if [ -d /user/report/jns ]
then
echo "Starting JReport Server"
/user/report/jns/bin/NJRServer.sh &
fi
;;
'stop')
if [ -d /user/report/jns ]
then
echo "Stopping JReport Server"
/user/report/jns/bin/CmdSender.sh localshutdown &
fi
;;
*)
echo " Usage: "
echo " $0 start (start JReport Server)"
echo " $0 stop (stop JReport Server)"
exit 1
;;
esac
exit 0
2. Create a soft link to /etc/rc2.d/S99jrserver.
ln -s /etc/init.d/jrserver /etc/rc2.d/S99jrserver
3. Create a soft link to /etc/rc0.d/K99jrserver.
ln -s /etc/init.d/jrserver /etc/rc0.d/K99jrserver
Running as a service on Linux
Running JReport Server as an OS service on Linux is more or less the same as with running on Unix.
Here it is assumed that your default start up rc is rc5.
Setting up XVFB
1. Install XVFB.
2. Write a script /etc/init.d/xvfb as follows, and make it executable.
#!/bin/sh
mode=$1
case "$mode" in
'start')
echo "start xvfb "
if [ -f /usr/X11R6/bin/Xvfb ]
then
/usr/X11R6/bin/Xvfb :1 -screen 0 1152x900x8 &
fi
;;
*)
echo " Usage: "
echo " $0 start (start XVFB)"
echo " $0 stop (stop XVFB not support)"
exit 1
esac
exit 0
3. Create a soft link to /etc/rc5.d/S97xvfb.
ln -s /etc/init.d/xvfb /etc/rc5.d/S97xvfb
Using rc to run JReport Server as a service
Assuming that JReport Server has been installed to /JReport/Server.
1. Write a script /JReport/Server/bin/JRServer as shown below, and make it executable. Here it is
assumed that JReport Server is running on a machine with IP address 127.0.0.1.
#!/bin/sh
DISPLAY=127.0.0.1:1.0
export DISPLAY
/JReport/Server/bin/JRServer -silent "[email protected]"
2. Write a script /etc/init.d/jrserver as follows, and make it executable.
#!/bin/sh
mode=$1
if [ ! -d /JReport/Server ]
then # JReport not installed
exit 1
fi
case "$mode" in
'start')
if [ -d /JReport/Server ]
then
echo "Starting JReport Server"
cd /JReport/Server/bin/;
JRServer -silent &
fi
;;
'stop')
if [ -d /JReport/Server ]
then
echo "Stopping JReport Server"
/JReport/Server/bin/CmdSender localshutdown &
fi
;;
*)
echo " Usage: "
echo " $0 start (start JReport Server)"
echo " $0 stop (stop JReport Server)"
exit 1
;;
esac
exit 0
3. Create a soft link to /etc/rc5.d/S98jrserver.
ln -s /etc/init.d/jrserver /etc/rc5.d/S98jrserver
4. Create a soft link to /etc/rc5.d/K98jrserver.
ln -s /etc/init.d/jrserver /etc/rc5.d/K98jrserver
If all has been carried out successfully, the installation of the service will now have finished. JReport
Server is now ready to run as a daemon process.
Running within an application server
In addition to running as a standalone server and as a service, JReport Server can also run as a servlet
inside a Java application server. Since JReport Server is implemented using servlets and JSPs, it can
work with any servlet-enabled web application server by assembling and deploying JReport Server as a
Web Application Archive (WAR) or Enterprise Application Archive (EAR).
There is a separate chapter about integration with different application servers - Integrating JReport
Server with a Java Application Server. It provides a general method for creating the deployable archive
and detailed procedures for deploying the archive into some popular application servers.
Basic Concepts
This chapter gives you some basic JReport Server concepts. You can first go through this chapter to
gain a general understanding about JReport Server before you use it. Also, while you are using JReport
Server, if you do not understand any of the basic concepts, you can refer to this chapter to get help.
This chapter discusses the following JReport Server main concepts:
●
Background tasks
●
Scheduling
●
Resource
●
Version
●
Security
●
Integration
●
JReport Server Cluster
Background tasks
JReport Server provides a background running system, which shows the status information of tasks
submitted using the Run, Advanced Run, or Background Run mode. Status information includes: report
name, report path and name, catalog path and name, running format, time when the task is started/
completed, time elapsed since the task is performed, and the status of the task. It allows you to view
detailed information in a timely fashion.
The records saved in the background running system are cleared under the following conditions:
●
●
●
●
JReport Server is restarted.
The maximum time limit specified for the report result life has been reached. By default it is 86400
seconds (24 hours).
The maximum time limit specified for the interval between a user logout and login has been reached.
By default it is 300 seconds.
If the number of records exceeds the number specified for the background task list (by default it is
100 records), the latest 100 records will be retained.
Scheduling
JReport Server provides a scheduling system which you can customize to suit your requirements. You
can submit a scheduled task from web page and URL or by calling the Server API methods. However,
before you can do this, you must first specify the report, catalog, task type and its launch type. In
addition, you can also customize notification messages to notify others of whether or not the task is
executed successfully.
User Task
In order to provide the means to run tasks defined outside of JReport on JReport Server, and to just
use JReport Server's schedule function, JReport provides a task named User Task. With this task, you
can implement a customized task with the schedule properties. Also, you can submit the user task from
a web page, or by calling JReport Server API methods.
After creating a class that implements the UserTask interface in the jet.server.api package and adding
the class to the class path, you can then submit the task either from a server web page or by calling
Server API methods. The task can then be run by the server at the scheduled times just as if it were a
report.
Trigger
The scheduling mechanism supports trigger conditions in addition to time conditions. Triggers are
managed by name in JReport Server, so each trigger must have a unique name. After creating a
trigger, you can submit a task that is bound with the trigger, and then fire the trigger to activate the
task at anytime.
Trigger conditions are based on event driven modes. The server does not care whether a customized
condition is ready. It only waits there for trigger firing events. Therefore, you determine whether the
condition is ready before firing a trigger.
Triggers can also work together with time conditions for activating a scheduled task.
Related topics:
●
Scheduling reports
Resource
JReport Server provides a resource system for managing a group of archive versions that can be processed or organized.
What is a resource
Generally, a resource refers to report or dashboard related material. To be exact, a resource in the JReport Server
reporting system is a conceptual node. There are different types of resources, such as catalogs, reports, dashboards,
library components, and their results. A resource can only hold versions of the same type.
Resource tree
All the resources are organized in a folder-tree structure. JReport Server defines an XML file called admin.xml, and the
resource tree conforms to this file. This file is maintained automatically by JReport Server.
For example, your company has two departments - Support and Marketing. Each department has its reports on their own
machine. There are some report documents that are submitted by the departments located on the machine where JReport
Server runs. Now, suppose you are the administrator, and you would like to organize these files and folders into the
Resource Tree. The following diagram may help you to figure out the framework on which you should build the resource
tree.
The resource tree consists of the following three layers:
●
●
●
Folder layer: Basic resource tree element that builds the main framework for the resource tree. There are four built-in
folders in the root of the resource tree - My Components, Public Components, My Reports, and Public Reports. A folder
can be mapped to a real file path.
Resource layer: An abstract layer, based on the Folder layer that hosts various types of archive versions and provides
user access to the versions.
Archive layer: A concrete layer, where the archive versions reside for executable resources, which function as the
leaves of the resource tree.
Public Reports and My Reports
There are two built-in folders in the resource tree root - Public Reports and My Reports for storing report resources. You
can create your own folders in either of them. The Public Reports folder and the My Reports folder cannot be deleted.
The Public Reports folder contains public report documents and executable reports, and can be accessed by everyone. All
folders except for the personal folders are public folders.
The My Reports folder is a personal folder. It contains personal report documents and executable reports. Each user has
one personal folder, specified by the administrator when the user account is created. The My Reports folder can only be
accessed by its owner, and the user has full control over his/her personal folder. This folder is the default output location
for reports run by the user.
Reports
There are two types of reports in JReport: page reports and web reports. A page report is a collection of report tabs and
each report tab can have multiple pages, while a web report has no report tabs and is always displayed as a web layout
report with just one page.
JReport Server supports viewing, advanced running, scheduling and managing of reports. The background run/scheduled/
active/completed record are based on report level.
When viewing a page report directly, if Page Report is set as the default report view format, the page report with all its
report tabs will be run. Otherwise, only the default selected report tab will be run.
When using Advanced Run to run a page report, you can only select one report tab in the page report to run.
When using scheduling to publish a page report to the versioning system or to disk, the Page Report Result and JReport
Result formats are based on the report level, that is, the report with all selected report tabs will be output to a single file.
As for the other formats, each selected report tab will be output to a separate file but you still have the convenience of
scheduling all the report tabs with a single schedule entry.
Public Components and My Components
Public Components and My Components are two built-in folders in the resource tree root for storing library components.
Their behaviors resemble the Public Reports and My Reports folders.
The Public Components folder contains public components and can be accessed by everyone. The My Components folder is
a personal folder that contains personal components for each dashboard user.
Library components
Library components are used to build dashboards. They are able to present data via intuitive components such as charts,
crosstabs, tables, and geographic maps. Library components are created and edited using JReport Designer, and then are
published to the component library on JReport Server for use in dashboards.
Related topics:
●
Managing resources
Version
JReport Server provides a versioning system for controlling the resources contained in the resource
tree. To understand what the versioning system is, first you have to understand the resource
mechanism in JReport Server. A resource in the JReport reporting system is a conceptual node, which
holds a group of archive versions that can be processed or organized in JReport Server. Information of
these versions is stored in the System DB database that JReport Server uses, while version files are
saved in the directory - <reporthome>\history.
What is a version
All the server resources in the resource tree are controlled by versions. A version is the fundamental
unit of the resource tree, and your resources might change over time. JReport Server uses a versioning
system to create and manage resources that have changed in content and properties owing to updates
issued upon them.
All the resources in the resource tree have versions. A large portion of resource management tasks are
done by managing resource versions.
Different version types
The versions in JReport Server fall into the following major categories:
●
●
●
Catalog Version
The version of a catalog file.
Report Version
The version of a report file.
Report Result Version
The version of a report result file.
The report result can be generated and maintained in two places - the resource tree and the built-in
version folder.
When you advanced run or schedule a report to publish to the versioning system, you can choose an
archive location to generate the report result. You can generate the report result in the built-in
version folder, the My Reports folder or the Public Reports folder in the resource tree.
The report results generated in the resource tree are standalone results and can have their own
versions, while those generated in the built-in version folder can only be bound with their respective
reports.
●
●
Dashboard Version
The version of a dashboard file.
Library Component Version
The version of a library component file.
Real path of versions
If you check the property of a version, you will find its real path. Remember that version information is
stored to a database, and version files are stored in the directory <reporthome>\history. For the
report InvoiceReport.cls, the report version's real path is <reporthome>\history\1
\JReport_System_User894485281\InvoiceReport.cls, which is the actual report result path on disk
and stored in the server database. That is, when you click the InvoiceReport.cls report result resource
on the server interface, you are accessing it on the disk, only the path to it is stored in the database.
And this works the same for the other types of versions.
Archive policy
JReport Server uses an archive policy to control the resource versions. You can control whether or not
to use multiple versions for a specific resource. Also, you can define the maximum number of versions
that can be listed in the version table.
The archive policy can be applied to a single resource individually, or to many resources in a folder as a
whole.
Related topics:
●
Managing versions
Security
JReport Server provides a security system for setting up and maintaining security on it, allowing you to
protect your resources from inappropriate access by other users.
To help you understand security in detail, the following security features with their concepts are
described below:
Realm
A realm is an abstract security concept, which hosts the resources and authentication entities on
JReport Server. There can be more than one realm on the server and each realm is independent from
others. The resources and authentication entities that reside in different realms are different.
At runtime, only one realm can be active and only the users and resources in the active realm are
accessible. A realm is identified by a unique name, which can contain any characters other than
forward slash (/) and backward slash (\).
The authentication entities consist of user accounts, group accounts and role accounts.
User
To use JReport Server, you must have a user account, which consists of a unique user name and
password. JReport Server verifies your identity when you type your user name and password and then
logs you on. If your user account has been disabled or deleted, JReport Server prevents you from
accessing the services that JReport Server provides, in order to ensure that only valid users have
access.
JReport Server comes with two built-in user accounts, which are admin and guest. The built-in user
accounts cannot be deleted. The admin user account can neither be deleted nor disabled.
Group
The principal group, which represents an organization of user accounts, is available for managing
users. Users or groups can then be added into a group as its child members, and therefore inherit the
resource and folder permissions from the group.
Role
Users must have certain user rights and permissions in order to perform tasks on resources. Roles,
which represent an aggregate of permissions, help you to efficiently assign the appropriate user rights
and permissions to users. Assigning roles to users gives them the user rights and permissions that they
require to perform their jobs with. A role can also be assigned to other groups or roles, and thus
groups or roles can inherit the permissions of other roles.
JReport Server comes with two built-in role accounts, which are administrators and everyone. The builtin role accounts cannot be deleted. The administrator role account can neither be deleted nor disabled.
Permission
Permissions, associated with resources and folders, are the rules that are granted to users to control
their access to resources and folders.
Permissions in JReport Server include:
Permission
Description
Visible
Allows or denies viewing object names in the resource tree or version table, such as
folders, resources, and archive versions.
Read
Allows or denies viewing object properties, versions, and, if it is a folder, folder
contents.
Write
Allows or denies publishing folders and resources, changing the properties (not
including permission settings) of the objects in the resource tree or version table, such
as folders, resources, and archive versions, and modifying version table settings.
Execute
Allows or denies running reports in normal and Advanced mode (for report type
resources only) or running dashboards in the view mode (for dashboard type resources
only) or opening visual analysis templates in Visual Analysis (for analysis type
resources only).
Edit
Allows or denies running dashboards in the edit mode (for dashboard type resources
only).
Schedule
Allows or denies submitting resources to schedules (for report type resources only).
Delete
Allows or denies deleting objects in the resource tree or version table, such as folders,
resources, and archive versions.
Grant
Allows or denies granting permissions to other users, groups or roles. Users, groups or
roles that have obtained the Grant permission are also endowed with the other
permissions, and can grant these permissions except the Grant permission itself.
Update
Status
Allows or denies updating report status, and if it is a folder, the status of reports in the
folder.
Privilege
Privilege is a mode which manages permissions. It can be used to manage different access permissions
unrelated with nodes. Privilege of JReport Server manages the following access permissions for users:
●
●
Publish
The privilege of publishing resources to JReport Server.
Advanced properties
The privilege of viewing advanced information of version properties such as catalog connections and
report related resources.
Alias
JReport Server organizes files and directories into a Resource Tree. Aliases are used to provide different
"views" of the tree for different users. For example, you may set an alias resource tree (based on the
resource tree) for Tanya, so that she can only see the marketing resource node and can directly enter
into the report folder she is interested in. An alias is a combination of users and resource nodes.
Organization
JReport Server administrator can organize users into different groups by creating organizations. An
organization is a group of users, groups, and roles that has its own administrator. The organization
administrator can define which users can use which dynamic connections within the organization.
Related topics:
●
JReport Security System
●
Managing security
Integration
JReport Server can be seamlessly integrated with any other Java application server to meet the
information delivery needs of a single department or an entire enterprise. It contains a rich set of APIs
that allow for seamless integration and is implemented using Java Servlet technology and Java Server
Page (JSP). These servlets and JSP pages enable the user to work with any Java EE compliant
application server that supports a Servlet Container and administer the JReport Server remotely
through a web browser.
Related topics:
●
Integrating JReport Server with a Java Application Server
JReport Server Cluster
A JReport Server Cluster is a distributed cluster in which a group of servers work together to provide
cluster-wide shared resources, security, schedules and version services. In a JReport Server Cluster, all
clustered servers play exactly the same role and any one can exit from the cluster any time.
The JReport Server Cluster provides the following major benefits:
●
●
●
Manageability: All users and resources can be controlled from a clustered server, remotely.
High-Availability: When one server fails to perform, the tasks running on it will be re-allocated to
other servers. If a server has already been fully utilized, the tasks sent to it will be allocated to the
other servers.
Scaleable: You can add or remove servers dynamically according to your needs.
There are many nodes (clustered servers) in a JReport Server Cluster. Every clustered server has the
same responsibility. You can set a clustered server to perform a specific role in a JReport Server Cluster
by configuring its properties.
Related topics:
●
JReport Server Cluster
Accessing JReport Server
You can access JReport Server through a web browser such as Internet Explorer, Firefox, or Google
Chrome.
Starting and logging onto JReport Server
To log onto JReport Server, first start the server via one of the following ways:
●
Double-click the JReport Server 13 shortcut on your desktop.
●
Click Start > All Programs > JReport 13 > Server > Start JReport Server.
●
Run the JRServer.bat/JRServer.sh file located in <install_root>\bin.
●
Run the startup file from a command prompt or shell. For example, assume that JReport Server has
been installed in C:\JReport\Server on Windows or /opt/JReport/Server on Linux, you can type
the following commands:
C:\>cd JReport\Server\bin
C:\JReport\Server\bin>JRServer.bat
$cd /opt/JReport/Server/bin
$./JRServer.sh
Then,
●
To access the JReport Console page:
1. Click Start > All Programs > JReport 13 > Server > JReport Server Console, or open a
web browser and set the URL to http://ip_or_hostname:port (by default, the port for
accessing the JReport Console page is 8888).
2. On the welcome page, type your user name and password as assigned by your administrator.
For first time users, the default user name and password are admin.
3. Click Login and the JReport Console page will be displayed.
●
To access the JReport Administration page:
1. Click Start > All Programs > JReport 13 > Server > JReport Server Administration, or
open a web browser and set the URL to http://ip_or_hostname:port (by default, the port for
accessing the JReport Administration page is 8889).
2. In the Sign in dialog, type your user name and password as assigned by the administrator. For
first time users, the default user name and password are admin.
3. Click Login and the JReport Administration page will be displayed.
Tip: If you don't know the IP address of the machine on which the server runs, and if it is the same
machine where you run JReport Server, you can use localhost instead of the IP address. You can also
open a console window such as telnet on the server machine and type hostname, then the name of
the host will be displayed.
Fast launch pad for local users
Local users can also access JReport Server in a fast way with the launch pad, which is a convenient
entry to access the server without having to start it. The launch pad provides some key functions of
JReport Server by setting up the connections to corresponding JReport Server JSPs, which are:
●
Viewing the JReport sample reports
●
Creating new reports
●
Scheduling to run reports by time or event
●
Configuring server profiles to customize the server interface and functionality
●
Managing security principals
●
Visiting the JReport Demo Center
To access the launch pad, click Start > All Programs > JReport 13 > Server > JReport Server
Launch Pad.
Additional login channel for admin users
JReport Server provides a special channel that automatically creates an extra user session for
management purposes if the license limit of the maximum number of concurrent users has been
reached. The extra user session cannot be used to run reports or submit schedules. It can only be used
by admin users for performing management operations. If your JReport Server license has a bounded
limit to the maximum number of concurrent users, this feature will take effect.
Only one extra valid user session can be created and used within this special channel at any time. If an
extra user session has already been created and it is still valid, your request for login will be prompted
with a confirmation page asking you whether or not to close the existing extra user session. If you
select Yes, a new extra user session will be created for you to perform management operations.
Otherwise, you will not be allowed to log onto JReport Server.
Note: If all normal user sessions have been used up, a request from a client viewer will be denied
permission to log onto JReport Server. Only a normal user session can use a client viewer to log onto
JReport Server, not the extra user session.
Logging off and shutting down JReport Server
To log off JReport Server, click the Logout link on the upper right corner of the JReport Administration/
Console page.
To shut down JReport Server normally:
●
●
In a standalone environment, click the Shut Down the Server button
on the JReport
Administration page, or click Start > All Programs > JReport 13 > Server > Stop JReport
Server.
In an integrated environment, shut down the application server according to the vendor's
instructions.
Also, JReport provides a feature for handling an abnormal system exit that enables the program to
close itself gracefully when the Java virtual machine (JVM) is terminated in response to a user
interrupt, such as typing ^C, or a system-wide event such as user logoff or system shutdown.
SSL in standalone JReport Server
JReport Server supports HTTPS requests in standalone mode. Secure ports for HTTPS requests should
use different ports from non-secure ports for HTTP requests. By default, port 6888 and 6889 are set as
the secure ports separately for accessing JReport Console UI and JReport Administration UI. The URL
for visiting JReport Server via HTTPS schema is like this:
https://IP_address or localhost:6888
SSL support is disabled by default. You need to enable it and configure corresponding settings in order
to use HTTPS schema to visit JReport Server UI. This can be done either on the JReport Administration
page or in the server.properties file located in the <install_root>\bin directory.
To enable SSL function via the administration UI:
1. Log onto the JReport Administration page. The default port is 8889.
2. Click Configuration on the system toolbar, and then select Service from the drop-down menu.
3. Check the Enable Secure Socket Layer Connection option.
4. Make sure that Secure Port and Secure Administration Port use different port numbers from Port
and Administration Port.
5. Specify the other settings about Keystore.
6. Click Save.
7. Restart JReport Server in order for the settings to take effect.
To enable SSL function in the server.properties file:
1. Open the server.properties file located in the <install_root>\bin directory.
2. Set httpserver.ssl.enable to true.
3. Set the other properties starting with httpserver.ssl to meet your requirements.
4. Save the server.properties file.
5. Restart JReport Server in order for the settings to take effect.
Notes:
●
●
JReport does not provide a keystore file since Jinfonet is not a trusted certificate authority and just
provides a Keystore File Path option for you to configure the location of your trusted keystore file.
There are many trusted authorities that can provide keystore files. Sun is one of them. Here is an
example of creating a keystore file provided by Sun: http://docs.sun.com/app/docs/doc/819-4674/
gdwpf?l=zh_TW&a=view.
JReport Server Monitor does not support SSL.
Working with Reports
After successfully logging onto the JReport Console page using the user name and password assigned
by your administrator via a web browser, you can then perform tasks according to your requirements.
For example, you can view reports in different formats and schedule tasks for the reports.
Pick a task from the following:
●
Running reports
●
Scheduling reports
●
Specifying parameter values
●
Using JSPs to print page reports
Related topics:
●
Managing resources
●
Managing versions
●
Managing tasks
Tip: You can customize the JReport Console > Resources page to suit your requirements by setting
your own preferences. To do this, click Tools > Preferences on the task bar of the Resources page,
then specify the settings in the Preferences dialog as required. For example, you can specify the default
viewing format when directly run a report from this page, set which columns will be shown in the
resource information table, and predefine the properties for each export format which will be applied
when you run or schedule a report on this page.
Running reports
If you know the default format for viewing reports and this format is what you expect, use direct
running. If you would like a different view format or to customize some other information such as
parameter values, the running priority, how to save the result, the expiration time, and so on, use
advanced running.
Direct running
Direct running reports is to use the default format setting to view the report result. For page reports
(for example, .cls) the default format is Page Report and they will run in Page Report Studio. For web
reports (.wls) they will be opened in Web Report Studio by default.
If the reports are created on JReport Server, the default format is controlled by the Default Format for
Viewing Report option in the Profile > Customize Server Preferences > General tab. When this option is
set to Page Report or Applet, web reports will run in Web Report Studio by default.
If the reports are created using JReport Designer, the default format is controlled by the Default
Format for Viewing Report property in the Report Inspector. If this property is set to <Server Setting>,
the viewing format will be determined by the above setting on server. For page reports this property is
available to each report tab in the reports, while for web reports it is available to each report.
Since a page report can contain multiple report tabs and these report tabs may have different default
format settings, for example, report tab 1 is Page Report, tab 2 HTML and tab 3 Excel. In this case,
there will be different direct running results according to which report tab was the last-time focused tab
in the page report when the page report was saved at report design time. If it was report tab 1, all the
tabs in the page report will be opened in Page Report Studio. If it was report tab 2 or 3, only tab 2 or 3
will be displayed, and this applies to all the other formats except Page Report.
To directly run a report, on the JReport Console > Resources page, browse to the report, then do one
of the following:
●
Click the name of the report in the Name column of the Resources page.
●
Select the report row and click Run > Run on the task bar of the Resources page.
●
Select the report row, right-click in the row and select Run from the shortcut menu.
●
Put the mouse pointer over the report row and click the Run button
on the floating toolbar.
Then, if the report contains parameters, the Enter Parameter Values dialog will be displayed. Specify
the parameter values according to your requirements.
Advanced running
1. On the JReport Console > Resources page, browse to the report you want to run.
2. Do either of the following:
❍
Select the report row, then on the task bar of the Resources page, click Run > Advanced Run.
❍
❍
Select the report row, right-click in the row and select Advanced Run from the shortcut menu.
Put the mouse pointer over the report row and click the Advanced Run button
floating toolbar.
on the
The Advanced Run dialog is then displayed.
3. In the General tab, for a page report, you need to select a report tab in the page report you want
to run (only one report tab in a page report can be run in Advanced mode at a time). If the report
has parameters, specify the parameter values. If there are multiple dynamic connections
available, expand the Select Dynamic Connection section and select a connection from the dropdown list. Click Connection Properties to view the connection information if needed. Then,
specify the other options as required.
4. In the Format tab, choose a format to view the report result, and set the other settings.
5. In the Archive tab, archive the report result version according to your requirements.
6. If you want to limit the amount of time that the report is allowed to run, in the Duration tab,
specify a time duration for the task, and ask JReport Server to cancel the task or to notify you or
someone else of the task status via e-mail if the task has not yet finished running when the task
duration is up. For detailed information, see Task-level timeout for advanced run and schedule
tasks.
7. Click Finish to view the report in the format you specified.
When running a page report in Page Report Studio, the report processing page will appear, on
which you can choose to cancel the running of the report, or to make the report run in background
mode. Click Cancel on this page if you decide to cancel, Background if you want the report to
run in background mode, or just wait for processing to complete. If you cancel the report from
running, you can choose whether to cancel the running query used by the report in the database
at the same time by configuring the JdbcDriversConfig.properties file. For details, refer to
Canceling running query.
See also Advanced Run dialog for details about options in the dialog.
Notes:
●
●
●
If you choose to view a page report in Page Report format, besides the selected report tab, all the
other tabs in the report will also be run.
When you run a report in Advanced mode in HTML format, the names of page navigation links in the
report, such as First, Previous, Next, and Last, can be localized according to your requirements. For
details, refer to Localizing page navigation links in HTML report outputs.
By default, the Duration tab is not displayed in the Advanced Run dialog. To make it available, the
Enable Task Duration option on the JReport Administration page > Configuration > Advanced panel
must be checked.
Running a page report in background mode
When you run a report in Page Report Studio, if the report contains a large amount of data, you need
to wait several minutes before the report results are displayed, and during this period, you have to
remain on the report processing page, or choose to cancel the run. Now JReport enables you to switch
running page reports to background mode.
To make a report running in Page Report Studio to run in background mode, on the report processing
page, click the Background button.
You can also specify to run page reports automatically in background mode after a specified time
period by setting preferences. To do this:
1. On the JReport Administration page, click Profile on the system toolbar and then select
Customize Profile from the drop-down menu. Or on the JReport Console page, click Profile on
the system toolbar, then click Customize Profile on the task bar of the Profile page.
2. Click the Page Report Studio > Properties > Advanced tab.
3. Check Background Mode Timeout and specify the time allowed for a page report to run in
foreground mode.
4. Save the settings, then when a report runs in Page Report Studio and the results have not yet
been generated after the specified time, it will be automatically switched to run in background
mode.
Reports running in background mode are listed in the Background Tasks table of the My Tasks page,
which shows detailed running information of the reports, such as report path and name, catalog path
and name, running format, time when the task is started/completed, and so on. Also, you can control
the status of the reports running in background mode according to your requirements. For example,
you can choose to delete, stop, or restart tasks (for details, see Managing tasks in the task tables).
When a report completes running in background, you can open it from the Background Tasks table, and
once the report is opened, the task will automatically be removed from the table.
Scheduling reports
JReport Server can run reports at a specified time or periodically by scheduling tasks for reports. The
scheduled tasks will be recorded by the server according to their different executing status.
Pick a topic from the following for details about how to schedule tasks in JReport Server:
●
Scheduling reports with dialog
●
Scheduling a task containing a bursting report
●
Scheduling a customized task using User Task
●
Recording scheduled tasks
●
Viewing scheduled report results
●
Importing and exporting scheduled tasks
●
Adding TaskListener
Notes:
●
●
When you schedule to publish a report to Page Report Result format, if the report is linked to
another report, in the Page Report Result file, the link will no longer be supported, and if you
schedule to publish the report to several formats and Page Report Result format is included at the
same time, the link will not be available in the other format outputs either.
When you schedule to publish a report to HTML format, the names of page navigation links in the
report, such as First, Previous, Next, and Last, can be localized according to your requirements. For
details, refer to Localizing the page navigation links in HTML report outputs.
Scheduling reports with dialog
You can schedule tasks for a specified report with dialog as follows:
1. On the JReport Console > Resources page, browse to the report you want to schedule to run.
2. Do either of the following:
❍
Select the report row, then on the task bar of the Resources page, click Run > Schedule.
❍
Select the report row, right-click in the row and select Schedule from the shortcut menu.
❍
Put the mouse pointer over the report row and click the Schedule button
toolbar.
on the floating
The Schedule dialog is then displayed.
3. In the General tab, specify the name for the task in the Schedule Name text box. For a page
report, you need to select the report tabs you want to run from the page report. You can choose
multiple normal report tabs or one bursting report at a time (for scheduling a bursting report, see
Scheduling a task containing a bursting report). If the report has parameters, specify the
parameter values. If there are multiple dynamic connections available, expand the Select
Dynamic Connection section and select a connection from the drop-down list. Click Connection
Properties to view the connection information if needed. Then, specify the other options as
required.
4. In the Publish tab, specify the type of the task.
Six task types are provided by JReport Server: publishing to version, publishing to disk, publishing
to e-mail, publishing to printer, publishing to fax and publishing to FTP. Choose the type you want
to publish, and then set the settings for the specified type.
5. In the Conditions tab, specify the time for when the task is to be performed in the Time sub tab,
and select or create a trigger to bind with the task in the Trigger sub tab.
6. In the Notification tab, specify to notify someone via e-mail of when the task is finished and
whether it is successful or unsuccessful.
7. In the Duration tab, specify a time duration for the task, and ask JReport Server to cancel the task
or to notify you or someone else of the task status via e-mail if the task has not yet finished
running when the task duration is up. For detailed information, see Task-level timeout for
advanced run and schedule tasks.
Note: By default, the Duration tab is not displayed in the Schedule dialog. To make it
available, the Enable Task Duration option on the JReport Administration page >
Configuration > Advanced panel must be checked.
8. Click Finish, and JReport Server will then perform the task.
See also Schedule dialog for details about the task types and settings in each tab.
The following are some specific scheduling examples:
●
Example 1: Publishing a report to the versioning system
●
Example 2: Publishing a report to the file system
●
Example 3: Publishing a report to e-mail
●
Example 4: Publishing a report to printer
●
Example 5: Publishing a report to fax
●
Example 6: Publishing a report to an FTP site
Example 1: Publishing a report to the versioning system
In this example, a task is set up and will be performed immediately. The generated result is asked to
be kept for 30 days.
1. On the JReport Console > Resources page, select the report row, right-click in the row and select
Schedule from the shortcut menu to display the Schedule dialog.
2. In the General tab,
a. Specify a name for the task in the Schedule Name text box.
b. In the Enter Parameters section, for a page report, you need to select the report tabs you
want to run from the page report. You can choose multiple normal report tabs or one bursting
report at a time. For scheduling a bursting report, see Scheduling a task containing a bursting
report.
c. If the report has parameters, specify the parameter values as required.
d. If there are multiple dynamic connections available, expand the Select Dynamic
Connection section and select a connection from the drop-down list. Click Connection
Properties to view the connection information if needed.
e. Expand the Report Information section, click Select Another Catalog to specify another
catalog for the report if required.
f. Select the report version and catalog version from the corresponding drop-down lists.
g. Assign a priority to the task from the Priority drop-down list.
h. Expand the Advanced section, if the report has a style group, check the Enable Style
Group checkbox and choose the style group.
i. Check the Enable Converting Encoding option if required and specify the encoding before
and after converting from the corresponding drop-down lists.
j. If Enable NLS is available, you can select it and then specify a language to display the report
contents with.
k. Define the encoding for the report by selecting from the drop-down list.
l. Check Use the default DB user and password defined in catalog.
m. Check the Add TaskListener to be Invoked option, and input the class name (for details,
see Adding TaskListener).
n. Check the Enable Auto Recover Task option to specify auto recovering settings.
3. In the Publish tab,
a. Click the To Version sub tab, then check Publish to Versioning System.
b. Select the required formats and set the format settings.
c. Check the Built-in Version Folder option in Archive Location to save the report result
version in the built-in version folder.
d. Set 0 for the Maximum Number of Versions.
e. Check the Result Auto-delete option and define the result to expire in 30 days.
4. In the Conditions tab, select the Time sub tab, define the time zone from the Time Zone dropdown list, then from the Time Type drop-down list, choose Run this task immediately.
5. If you want to notify someone of when the task is finished by sending an e-mail, go to the
Notification tab and then set the settings.
6. If you want to specify a timeout for the task, specify the settings in the Duration tab as required.
7. Click Finish to have the task performed.
Then, click My Tasks on the system toolbar. While the task is being performed, you can see a record
of it in the Running tab. On completion it will be put into the Completed tab.
Notes:
●
When publishing a report to XML format, if you want to use the URL to get the .xsd file, follow the
steps below:
1. Put the existing XML schema file in <intall_root>\public_html.
2. Input http://IP address:8888/name of the existing XML schema file.
●
There is another way to publish the report result to version. If you have set the property server.
version.from.temp to true in the server.properties file in <install_root>\bin, or selected the option
Enable "Publish to Versioning System" for Background Tasks View on the JReport Administration page
> Configuration > Advanced panel, you will get the link Publish to Version System on the system
toolbar of the JReport Console page. Click the link to publish the result to version.
Example 2: Publishing a report to the file system
In this example, you will learn how to set up a task to publish the report result in various file formats to
the file system repeatedly at the start of each month.
1. Take steps 1 and 2 as in Example 1.
2. In the Publish tab of the Schedule dialog, click the To Disk sub tab, select the required format,
specify the result location, and set the format settings according to your requirements.
3. In the Conditions tab,
a. In the Time sub tab, define the time zone from the Time Zone drop-down list, then from the
Time Type drop-down list, choose Run this task periodically.
b. In the Duration box, specify a time period for when the task will be performed.
c. Select Monthly from the Date drop-down list and keep the default to run the first day of
every 1 month.
d. Keep the Time settings as default.
e. If you also want to set an event which needs to occur before running the report, select a
trigger to bind with the task from the Select a trigger to bind drop-down list in the Trigger
sub tab, then specify the trigger logic with time condition.
For detailed information about the logic between the trigger condition and the time condition,
see Trigger tab.
4. If you want to notify someone of when the task is finished by sending an e-mail, go to the
Notification tab and set the settings.
5. If you want to specify a timeout for when the scheduled report will be allowed to run, specify the
settings in the Duration tab as required.
6. Click Finish to have the task performed.
Then, click My Tasks on the system toolbar, you will see that the scheduled task has been recorded in
the Scheduled tab. Since you have not specified the duration Run until a time for this task, it will not
stop being performed until you delete or disable it from the Scheduled tab.
Notes:
●
●
●
When you specify to publish the report result to the server resource tree, if the specified folder has a
real path, the result will be put to the real path. Otherwise it will be put to the default disk location
where server resources are.
If you specify to publish the report result to a non-existent folder on disk, JReport Server will
automatically create it.
If you use a fixed name to perform the task periodically, only the most recently generated report
result will be kept. In order to keep the report result generated every time, you should use the
dynamic result file name. Similarly, you are able to input the dynamic directory path to avoid report
management difficulties, since when a fixed directory path is specified, too many results may be
generated in one directory. For more information, see Appendix 5: Dynamic names.
Example 3: Publishing a report to e-mail
In this example, you will learn how to set up a task to publish the report result to e-mail.
1. Take steps 1 and 2 as in Example 1.
2. In the Publish tab of the Schedule dialog, click the To E-mail sub tab, then from the Mail To list,
select to whom the report result will be sent. If required, click the Edit button to edit the specified
e-mail.
If you want to create another e-mail, click the New button, then fill in every field, select the
format in which you want to export the report result and set the settings according to your
requirements. When you choose to specify a report result as an attachment to e-mail, you need to
specify a file name for the attachment. For details about settings of creating a new e-mail, refer to
Schedule dialog - To E-mail.
3. In the Conditions tab, select the Time sub tab, define the time zone from the Time Zone dropdown list, then from the Time Type drop-down list, choose Run this task immediately.
4. If you want to notify someone of when the task is finished by sending an e-mail, go to the
Notification tab and set the settings.
5. If you want to specify a timeout for the task, specify the settings in the Duration tab as required.
6. Click Finish to have the task performed.
Then, click My Tasks on the system toolbar. When the task is being performed, you can see a record
of it in the Running tab and on completion it will be put into the Completed tab.
Example 4: Publishing a report to printer
In this example, you will learn how to set up a task to publish the report result to a printer.
1. Take steps 1 and 2 as in Example 1.
2. In the Publish tab of the Schedule dialog,
a. Select the To Printer sub tab and then check Publish to Printer.
b. Select a JDK print method for the report result in the Select Print Method field.
c. Type a name with the path of the printer in the Printer field.
3. In the Conditions tab, select the Time sub tab, define the time zone from the Time Zone dropdown list, then from the Time Type drop-down list of the Time tab, choose Run this task
immediately.
4. If you want to notify someone of when the task is finished by sending an e-mail, go to the
Notification tab and set the settings.
5. If you want to specify a timeout for the task, specify the settings in the Duration tab as required.
6. Click Finish to have the task performed.
Then, click My Tasks on the system toolbar. When the task is being performed, you can see a record
of it in the Running tab and on completion it will be put into the Completed tab.
Note: When there is no printer connected with JReport Server, and you schedule to publish a report to
a printer, the server may crash or throw an exception.
Example 5: Publishing a report to fax
In this example, you will learn how to set up a task to publish the report result to fax. Before you can
fax the report result, you must first have your modem configured. Otherwise a warning message will be
displayed when you try to export to fax.
1. Take steps 1 and 2 as in Example 1.
2. In the Publish tab of the Schedule dialog, click the To Fax sub tab, check the Publish to Fax
option and then fill in every field and set the settings according to your requirements.
3. In the Conditions tab, select the Time sub tab, define the time zone from the Time Zone dropdown list, then from the Time Type drop-down list, choose Run this task immediately.
4. If you want to notify someone of when the task is finished by sending an e-mail, go to the
Notification tab and set the settings.
5. If you want to specify a timeout for the task, specify the settings in the Duration tab as required.
6. Click Finish to have the task performed.
Then, click My Tasks on the system toolbar. When the task is being performed, you can see a record
of it in the Running tab and on completion it will be put into the Completed tab.
Example 6: Publishing a report to an FTP site
In this example, you will learn how to set up a task to publish the report result to an FTP site.
1. Take steps 1 and 2 as in Example 1.
2. In the Publish tab of the Schedule dialog,
a. Click the To FTP sub tab, then click the New button to set up a new FTP site or click the Edit
button to edit a specified FTP site in the FTP To list.
b. Fill in every field, select the format in which you want to send the report results and then set
the settings according to your requirements.
3. In the Conditions tab, select the Time sub tab, define the time zone from the Time Zone dropdown list, then from the Time Type drop-down list, choose Run this task immediately.
4. If you want to notify someone of when the task is finished by sending an e-mail, go to the
Notification tab and set the settings.
5. If you want to specify a timeout for the task, specify the settings in the Duration tab as required.
6. Click Finish to have the task performed.
Then, click My Tasks on the system toolbar. When the task is being performed, you can see a record
of it in the Running tab and on completion it will be put into the Completed tab.
Note: Dynamic result name for FTP task is currently not supported.
Scheduling a task containing a bursting report
In a large enterprise reporting deployment, it is important to handle both large amounts of data as well
as a large number of users. Report bursting enables running a report once and distributing the report
results to multiple recipients who each will receive a subset of the report results.
Bursting reports can be distributed to e-mail or FTP addresses, to disk, to the JReport versioning
system, or to the security system members such as users, groups, and roles.
End users can submit a schedule task which contains only one bursting report to JReport Server. When
a bursting task is activated, it will create a main bursting task and some sub bursting tasks. The
system will guarantee bursting tasks compete with normal tasks for system resources. The bursting
tasks can be given lower priority if desired (set queue.policy to 1).
●
●
Main bursting task: It is responsible for getting/splitting data and distributing work to the sub
tasks. There can be only one main bursting task for a sub bursting task.
Sub bursting task: It is responsible for generating the report result according to split data and
sending the result to the address of the bursting recipient.
For details about what is a bursting report and how to design a bursting report, see Report Bursting in
the JReport Designer User's Guide.
On JReport Server, direct running and advanced running actions are supported for normal reports but
not bursting reports. A report containing only bursting report tabs cannot be run directly or in
Advanced mode, it must be scheduled.
Scheduling is supported for both types of reports excluding the combination of the two types: for
normal reports, multiple reports can be scheduled at a time; however for bursting reports, only one can
be scheduled. For a scheduled bursting task, seven kinds of result file formats are supported: HTML,
PDF, Excel, Text, RTF, XML, and PostScript. In addition, when scheduling to run a bursting report, you
can make it generate not only the bursting result by applying bursting schemas but also the nonbursting result based on whole data without data splitting.
Scheduling a bursting report to generate bursting result
Though a bursting report may have one or more bursting schemas, you need apply one or more of
them in order to get a bursting result. To do this, select a bursting report and schemas, and then
specify required parameter values in the General tab of the Schedule dialog. Then a tab named
Bursting Result is displayed in the Publish tab and only the corresponding sub tabs that are defined in
the selected bursting schemas' recipients in JReport Designer are available. For example, a bursting
report has three bursting schemas: Schema 1 defines recipient E-mail and Disk, Schema 2 defines
recipient FTP, and Schema 3 defines recipient JReport Server Version. If Schema 1 and Schema 3 are
selected, only To E-mail, To Disk, and To Version sub tabs will be shown in the Bursting Result tab of
the Publish tab for the bursting result.
Once you choose to schedule to run a bursting report, you should at least specify the schema you want
to apply to the selected bursting report or select Non-bursting result in order to submit the task.
The following list tells which tab will be displayed in the Publish > Bursting Result tab of the Schedule
dialog for which recipient address specified in bursting schema.
Recipient
Sub tab in the Publish tab
E-mail
To E-mail
FTP
To FTP
Disk
To Disk
JReport Server Version
To Version
JReport Server User/Group/Role - User E-mail To E-mail
JReport Server User/Group/Role - User
Private Folder
To Version
When scheduling a bursting report, you needn't specify the destination in the Publish tab since the
recipient addresses have been included in the bursting schema. However, you are allowed to give a file
name to the subset of report result instead of using the default name.
Default name for bursting result files
Sometimes you may not want to specify a file name for each bursting result when defining recipients.
The bursting system will give it a name as generated by the system.
The default name format is: ReportName + "_" + BurstingKey + suffix (result format type). When
there are multiple bursting key columns, connect each one by the character "_".
Converting to String
When a bursting key is of one of the following data types, it will be converted into String so as to make
a valid result file name:
●
●
●
Integer, Float, Character: Same as Java, these data types are transferred to string directly.
Date and Time: All data and time formats will be transferred to a date format: yyyy-MM-dd hh:mm:
ss.
Currency: Currency will be transferred to the number without the currency mark ($ or others).
Name length
In the JReport Server resource system, the resource name only supports up to 64-character length. If
a bursting result file name is longer than that, the system will trim it down automatically.
In order to avoid using the same name in the same path, an index will be appended to the result name,
for example: report1_USA_Maryland1.pdf, report1_USA_Maryland2.pdf.
Notes:
●
All bursting sub results will apply the security information of the bursting task submitter.
●
When running a page report containing both normal and bursting report tabs:
For direct running:
When running it to Page Report format, only the normal report tabs are opened.
When running it to other formats, if the default focused report tab is a normal report, it will be
opened directly; if the default focused report tab is a bursting report which cannot be run, a warning
message will be displayed asking the end user to select a normal report tab to run using advanced
run.
For advanced running:
You can only choose the normal report tabs to run.
Scheduling a bursting report to generate non-bursting result
Besides generating bursting result for a bursting report, you can also generate non-bursting result for
the report without applying any bursting definition, which is based on full data without data splitting.
To generate non-bursting result, select the Non-bursting result option in the General tab of the
Schedule dialog. Then a tab named Non-bursting Result appears in the Publish tab, and all these sub
tabs - To Version, To Disk, To E-mail, To Printer, To Fax, and To FTP - are available in this tab for the
non-bursting result.
Scheduling a customized task using User Task
In order to meet the requested requirement to run tasks defined outside of JReport on JReport Server,
and to just use JReport Server's schedule function, JReport has provided a task named User Task. With
this task, you can implement a customized task with the schedule properties. You can also submit the
user task from a web page, or by calling the JReport Server API methods.
To schedule a customized task using User Task:
1. Create a task class that implements the UserTask interface and add the path of the class file to
the ADDCLASSPATH variable in setenv.bat, which is located in <install_root>\bin. You can find
the interface in the jet.server.api package available in <install_root>\help\api. JReport
provides a demo class APIDemoDynamicExportTask.java in <install_root>\help\samples
\APIServer for your reference.
2. Create a task properties file defining the formats of exporting the task. For example, the content
of the properties file is:
jrs.rst=result_rtf
jrs.pdf=true
jrs.text=true
jrs.excel=true
jrs.ps=true
jrs.html=result_html
3. Submit the task either from a server web page or by calling Server API methods. The task can
then be run by the server.
❍
To submit the customized task from a server web page:
a. On the JReport Console > Resources page, browse to the desired report, put the mouse
pointer over the report row and click the Schedule button
The Schedule dialog is then displayed.
on the floating toolbar.
b. Specify the settings in the General, Publish, Conditions, and Duration tabs as required.
Here the Publish tab settings should be switched to those of User Task by clicking the link
on the right bottom of the tab. Then, the name of the task class file you have defined that
implements the UserTask interface and the task properties that define the export formats
must be provided. You can either input the task properties manually or import them from
the task properties file that you have created.
c. Upon finishing, click Finish to submit the task.
❍
To submit the customized task by API methods:
a. Set the user task class name to the property value of APIConst.TAG_TASK_CLASS.
b. Define the user task properties with the property APIConst.TAG_USER_TASK_PROP with
the formats as follows: jrs.user_task_prop= jrs.rst=result_rtf&jrs.pdf=true&jrs.
text=true&jrs.excel=true&jrs.ps=true&jrs.html=result_html. Since the jrs.user_task_prop
is used to transfer multiple user task properties, the values set to this property must be
formatted to be separated with "&" character.
c. Set a display name for the class with the property APIConst.
TAG_USER_TASK_DISPLAY_NAME.
d. Except for the above properties, define the other schedule properties as you do with a
default task, see APIDemoPublishRpt.java in <install_root>\help\samples\APIServer
for reference. Then following the API demo you can submit a customized task on the server.
Click My Tasks on the system toolbar. When the task is being performed, you can see a record of it in
the Running tab and on completion it will be put into the Completed tab.
Note: You can either schedule to use the Default Task or the User Task at one time. If you specify to
schedule a report as a default task, you will not be able to schedule it as a user task, and vice versa.
Recording scheduled tasks
JReport Server records every scheduled task. Click My Tasks on the system toolbar of the JReport
Console page, then the following tabs will be displayed: Scheduled, Running, and Completed. The tasks
are recorded in different tables according to their executing status. A task is placed in the Scheduled
table as soon as it is submitted by the user. It will go to the Running table when it is running, and
when it is finished by JReport Server, it will then go to the Completed table.
Related topics:
●
Managing tasks
Viewing scheduled report results
When a scheduled task is finished, you can view the results of the scheduled report as required. To
view the results, first of all you need to know the corresponding results' location. To get the location
information:
1. On the JReport Console page, click My Tasks on the system toolbar, then click the Completed
tab, where all the successfully scheduled tasks are recorded.
2. Locate the task in the tab and click the name of the task in the Schedule Name column.
3. In the Result Details table, the location information of the scheduled results are available in the
Details column.
Viewing results scheduled to version
To view report results that are scheduled to version, you can choose whether to view via the JReport
Console page or via URL.
Viewing via the JReport Console page
One way to view results that are scheduled to version on the JReport Console page is via the scheduled
task records. To do this:
1. Click My Tasks on the system toolbar, then click the Completed tab.
2. In the tab, locate the right task and click the name of the task in the Schedule Name column.
3. In the Result Details table, the links to different result formats are available for viewing in the To
Version row.
And another way to achieve the same purpose is via the server resource tree which to some extent
varies with the archive location type specified in the Publish > To Version tab:
●
If the archive location has been set to Built-in Version Folder:
1. On the JReport Console > Resources page, browse to the row that the original report is in.
2. Do either of the following:
■
Select the report row and click Tools > Version on the task bar of the Resources page.
■
Select the report row, right-click in the row and select Version from the shortcut menu.
■
Put the mouse pointer over the report row and click the Version button
toolbar.
on the floating
3. In the Report Result Versions tab, the scheduled results of different format types are listed in
the Result column. Click the format links or action buttons to view the results.
●
If the archive location has been set to My Reports Folder or Public Reports Folder, which requires
providing a path and a name for the scheduled result in the server resource tree:
1. On the JReport Console > Resources page, browse to the row that the result is in.
on the floating
2. Put the mouse pointer over the result row and click the Version button
toolbar (or you can use one of the other two methods shown in the above procedure to display
the version table).
3. In the Result Versions tab, the scheduled results of different format types are listed in the Result
column. Click the format links or action buttons to view the results.
Tip: The unviewed version results are highlighted in bold. You can cancel the highlighting by setting
the property web.version.mark_unviewed to false in the server.properties file in <install_root>\bin.
Viewing via URL
For the report results that are scheduled to version, you can also view them via URL. One important
thing in the URL method is that you need to know the file name of the result that you want to view. To
get this information, you can take the steps explained at the beginning of the document.
Using command jrs.view_ver_rst
See the example:
http://localhost:8888/jrserver/SampleReports/SampleReports.cat/EmployeeInformation.cls?
jrs.cmd=jrs.view_ver_rst&
jrs.hist_file=1%5cJReport_System_User327406359%5cEmployeeInformation.rst&jrs.
result_type=1.
See details about the usage of the command jrs.view_ver_rst.
Using viewVersion.jsp
For example:
http://localhost:8888/jinfonet/viewVersion.jsp?jrs.cmd=jrs.view_ver_def&jrs.
rst_version=2&jrs.ver_suff=.html&
jrs.report=%2fSampleReports%2fEmployeeInformation.cls&type=rstfile&jrs.path=%
2fSampleReports%2fEmployeeInformation.cls
Notes:
●
To view RSD version results using JSP, you should use dhtml.jsp instead of viewVersion.jsp. For
example:
http://localhost:8888/dhtmljsp/dhtml.jsp?jrs.rst_version=10&jrs.report=/SampleReports/
Banded_Link.cls&type=rstfile&jrs.path=/SampleReports/Banded_Link.cls
●
When viewing a scheduled page report result with cached report bursting via URL, you should add
jrs.is_pls_result=true in the URL, for example: http://localhost:8888/dhtmljsp/dhtml.jsp?
jrs.rst_version=1&jrs.is_pls_result=true&jrs.report=/SampleReports/PLS.
cls&type=drstfile&jrs.path=/SampleReports/PLS.cls
Viewing results scheduled to disk
When scheduling a report to disk,
●
If you choose Publish to Server Disk Path, you are required to provide a disk file path and file name
with correct format type as the suffix for each report tab in the report. After scheduling succeeds,
you can find the corresponding result files available at the specified location on the computer where
JReport Server is installed.
●
If you choose Publish to Server Resource Tree, you are required to provide a path following the
server resource tree and file name with correct format type as the suffix for each report tab in the
report. For example,
❍
To follow the My Reports folder path, start with "/USERFOLDERPATH/admin/".
Example: /USERFOLDERPATH/admin/report1.pdf
❍
To follow the Public Reports folder, start with "/".
Example: /SampleReports/report2.html.
If the specified folder which is the parent folder of the result file has a real path, the generated result
file will be saved to the real path; if the folder doesn't have a real path, the generated result will be
saved to <server_install_root>/jreports/, which is the mapped disk path of the root node "/" in
the specified path.
Viewing results scheduled to e-mail/printer/fax/FTP
When a report is scheduled to e-mail, printer, fax, or FTP, you can view the scheduled results if the
specified addresses or locations are available to you.
Importing and exporting scheduled tasks
In JReport Server, you can export a scheduled task to a script file which will then be saved on your own
disk as a script file. In addition, you can import a script file from the disk file to generate a scheduled
task.
To export a scheduled task to a script file and save it in the disk:
1. On the JReport Console page, click My Tasks on the system toolbar.
2. In the Scheduled tab, select the rows that one or more scheduled tasks are in.
3. Click Tools > Export to Script on the task bar of the My Tasks page (if only one task is selected,
you can also right-click in the task row and select Export to Script from the shortcut menu, or
put the mouse pointer over the task row and click the Export to Script button
floating toolbar), then modify the script text in the Edit Script box as required.
on the
4. Click OK to export the specified scheduled task to a script file.
5. Specify the directory and name for this script file in the File download dialog.
To import a script file from your disk:
1. On the JReport Console page, click My Tasks on the system toolbar, then select the Scheduled
tab.
2. Click New Schedule on the task bar of the My Tasks page.
3. In the New Schedule dialog, check the option Import Script to Create Schedule.
4. Click the Browse button to select a script file from your disk file, then click OK to import the
specified script file and modify the script text in the Edit Script box as required.
5. Click OK to generate a scheduled task.
Note: If you just updated from an older version of JReport Server, there may be some old scripts
saved in your server. In order to use these old scripts, you can click the Import old script from
server link in the Import Script page to select an old script to import it to generate a scheduled task.
To use this link, you must logon JReport Server as an administrator role.
Adding TaskListener
When viewing or scheduling a report, JReport Server enables you to call your Java application before or
after the process.
In JReport Server, a TaskListener interface has been provided in the package jet.server.api for
receiving task events before or after running. You can specify one Java class to implement this
interface for a task event. When the event of this task occurs, the corresponding methods in the
listener will be invoked. The interface contains two methods: beforeRun and afterRun, enabling you to
set your Java application call before or after the process of viewing a report or setting up a schedule.
Your applications will return true or false. For true, JReport Server will go on running. While for false,
JReport Server will stop there.
Below is an example illustrating how to add TaskListener when setting up a schedule on a report.
1. Develop your Java class to implement the interface. Here TestTaskListener.java is used, which is
available in <install_root>\help\samples\APITaskListener.
2. Compile TestTaskListener.java to generate the class file.
3. Edit the batch file setenv.bat in <install_root>\bin. Assuming that TestTaskListener has been
saved in C:\JReport\Server\tasklistener, add the path of the class file (C:\JReport\Server
\tasklistener) to the ADDCLASSPATH variable in setenv.bat.
4. Start JReport Server and set up a schedule on a report, check Add TaskListerner to be Invoked
in the General tab of the Schedule dialog, then input the class name. In this example, input
TastListener, and then submit the task.
5. In this example, the class returns True.
Print out the task and schedule properties before and after running the task. You will then get task
and schedule information in the command window before and after the task is run.
You can also define properties of your own and transmit them through ServerInfo. To do this, use
APIConst.TAG_USERDEFINED_PROPERTY_PREFIX as the prefix for the properties.
For example, if you want to transmit the properties host_name, host_ip and hosp_protocol, you will
need to insert the properties, before calling the method runTask, into the properties named prop, as
follows:
prop.put(APIConst. TAG_USERDEFINED_PROPERTY_PREFIX+"host_name", "host");
prop.put(APIConst. TAG_USERDEFINED_PROPERTY_PREFIX+"host_ip", "127.0.0.1");
prop.put(APIConst. TAG_USERDEFINED_PROPERTY_PREFIX+"host_protocol"+ "TCP/IP");
You can get the value of the properties listed above through the server info object, serverInfo, in the
method beforeRun or afterRun of the TaskListener class. See the example below:
host_name=serverInfo.getTaskProperties().get(APIConst.TAG_USERDEFINED_
PROPERTY_PREFIX+"host_name");
host_ip=serverInfo.getTaskProperties().get(APIConst.TAG_USERDEFINED_
PROPERTY_PREFIX+"host_ip");
host_protocol=serverInfo.getTaskProperties().get(APIConst.TAG_USERDEFINED_
PROPERTY_PREFIX+"host_protocol");
Note: All properties without the prefix APIConst.TAG_USERDEFINED_PROPERTY_PREFIX will be denied
and discarded by JReport Server.
Specifying parameter values
When running or scheduling reports with parameters, you may need to specify values for the parameters.
The way to specify a parameter value varies with the type and properties of the parameter. Here are
several ways you can use to specify parameter values:
●
In the parameter value combo box, input the value manually or select the required one from the dropdown list. If you have chosen to automatically save parameter values, the saved value groups will be
available on the top of the parameters' value lists for selection.
●
Select or unselect the checkbox to specify a Yes/No value.
●
Click the button
●
Click the calendar button
to specify a date and time value using either calendar or expression in the
Calendar dialog. If you use an expression to specify the value, when you hover the mouse pointer over
this value, a tip will appear showing its expression. Click on the value, the expression will be displayed
in the value text box and you can edit the expression in the text box directly if you want. After editing,
when you click elsewhere outside of the value text box:
❍
❍
●
to specify multiple values in the Enter Values dialog.
If the edited expression is correct, a new value calculated by the expression will be displayed in the
parameter value text box.
If the edited expression is wrong, no value will be created and the expression itself will be displayed
and highlighted in red in the value text box. Correct the expression, or click the calendar button to
specify a value.
Click the Use Saved Values button
and select a previously saved parameter value group to apply
to the report. For details, see Manually saving parameter values.
Note: You are recommended not to use blank as the thousands separator in Number-typed parameter
values under French locale, otherwise your input will not be correctly recognized because of a JVM bug.
For details, see http://bugs.sun.com/view_bug.do;jsessionid=c8cdaf911b20fffffffffd9fc6340b30d670?
bug_id=4510618.
This document also introduces some useful techniques for setting parameter values.
Saving parameter values for reuse
When specifying parameter values for reports, you may want to save the specified parameter values for
reuse next time. JReport provides two ways of saving. One is users decide when and which parameter
values to save, the other is JReport saves each applied or submitted parameter values automatically.
When the saved number in either way reaches the maximum, the oldest record will be removed. The
number is calculated on a user-report basis. Take a report with two parameters for an example,
supposing the maximum number is set to 3. Each user can save at most three groups of parameter
values for the report. Each group contains the values of the two parameters.
To switch on the function of saving parameter values, go to the Profile > Customize Server Preferences >
Advanced tab, select Yes to the option Enable Saving Parameter Values, select a way to do the saving:
Manually or Automatically, and then specify a maximum number to limit the saved value groups which is
called the auto complete parameters list for each user-report pair.
Manually saving parameter values
When you have chosen to manually save parameter values, the Use Saved Values button
will be
available on the upper right corner of the parameter page. By clicking this button, you will get the
following:
●
Value List
The value list contains all the parameter value groups you have saved for the report. Select a group to
apply all the values in the group to the corresponding parameters. You can also remove any of the
unwanted value group by selecting it from the list and then clicking
●
next to the value list.
Save Values
Saves the current displayed parameter values as a group for reuse afterwards. To do this, type a name
for the saved group in the text box which shows "Save current values into list" and then click the Save
Values button
. The saved group will then be added into the value list above. Once it reaches the
maximum number, the latest group will replace the oldest.
Using automatically saved parameter values
When you have chosen to automatically save parameter values, each time a user submits a group of
parameter values to a report, the group is saved by JReport automatically. The next time the same user
runs the report, the auto saved parameter values will be available in the parameters' value lists for
selection on the parameter page.
Customizing default parameter values
When specifying parameter values for a report, if you would like the current specified parameter values to
be saved as the default values for the parameters next time when you run or schedule the report, select
the Save as default option on the parameter page (to make this option available, you need to make sure
the Enable Setting Default Parameter Values For option is selected for the corresponding resource in the
Profile > Customize Server Preferences > Advanced tab).
If you want the saved default parameter values to be applied directly to the report next time when you
run it without popping up the Enter Parameter Values dialog, select the option Do not show the screen
again in the dialog (to make this option available, you need to make sure the Enable Hiding Initial
Parameter Dialog For option is selected for the corresponding resource in the Profile > Customize Server
Preferences > Advanced tab). However, if the last-time saved default values cannot completely match the
current report parameters, the dialog will still be displayed. This option only hides the parameter dialog
popped from operation on the console. It does not affect the case of running report using URL way.
In addition, JReport provides you with the Parameter Settings dialog which allows you to pre-customize
the default parameter values for a report before running it. This dialog can also be used to show the Enter
Parameter Values dialog again after it has been hidden. To do this, check Re-enable Parameter Screen
in the dialog.
The above options are user-report level settings, that is to say, they take effect when both the same user
and report are matched. This also applies to admin users, and therefore admin cannot customize the
settings for all users.
Using built-in functions to set date and time parameter values
For a parameter of the Date, DateTime, or Time type, you can customize a dynamic date and time value
by creating an expression using built-in functions.
To do this:
1. In the places where you are able to specify a value for the parameter, you may see the calendar
button
. Click this button and the Calendar dialog is displayed.
2. The Template drop-down list on the right provides some predefined expressions for you to use. You
can customize your own expression either based on an existing template or by directly editing the
contents in the Expression text box.
If you cannot see the Template label on the right, click >> on the bottom left corner.
3. JReport's built-in Date/Time formula functions are available for inserting into your expression. To
make use of them, click
to display the functions.
4. The Preview box calculates the result of the current expression. Each time you modify the
expression, you can click in the box to refresh the result. If it is an invalid expression, an error
message will be shown in the box and no change will be made to the calendar and the currently
selected date/time will be remained in the calendar.
5. When done, click OK to add the value.
See also Calendar dialog for additional help about the options in the dialog.
When running reports via URLs, you can also use expressions to specify date and time parameter values.
The format is Parameter_Name={"exp":"Complete_Expression_String", "SelectedDate":"'MM/dd/yyyy"}.
If the expression does not contain the function SelectedDate(), there is no need to add this part "SelectedDate":"'MM/dd/yyyy" and the format is Parameter_Name=
{"exp":"Complete_Expression_String"}. For example, to specify p_EndDate=today(), write it as
p_EndDate={"exp":"today()"}. The following is an example of running the CustomerAnalysis.cls:
http://localhost:8888/jinfonet/runReport.jsp?jrs.cmd=jrs.web_vw&jrs.catalog=%
2fSampleReports%2fSampleReports.cat&jrs.report=%2fSampleReports%2fCustomerAnalysis.
cls&jrs.param$P_StartDate=01/01/2010&jrs.param$p_EndDate={"exp":"today()"}&jrs.
result_type=8
Using JSPs to print page reports
JReport Server provides the following demo JSPs which enable you to print a page report without any view in the client
side, and they are available in <install_root>\help\samples\JSPSamples\PrintReport.
●
●
printDemo.jsp
Provides frames to load printCustomerlist.jsp and printReport.jsp.
printCustomerlist.jsp
Shows how to set parameters for printing the demo report CustomerAnalysis.cls by using the ViewerApplet. This JSP
calls printReport.jsp. If you want to print the other reports, you can follow this JSP file as an example to write your
own JSP. In your own JSP, you should modify the values of "cat" and "rptName".
String cat = "/SampleReports/SampleReports.cat"; //request.getParameter(APIConst.TAG_CATALOG);
String rptName = "/SampleReports/CustomerAnalysis.cls"; //request.getParameter(APIConst.TAG_REPORT);
●
printReport.jsp
Shows how to print reports by using the ViewerApplet. The example JSP printCustomerlist.jsp calls this JSP.
Before running the JSPs, copy them to <intall_root>\public_html\jinfonet. Then, start JReport Server and access
printDemo.jsp using the URL http://localhost:8888/jinfonet/printDemo.jsp. The following page appears:
PrintInCurrentFrame
Specifies to call printReport.jsp and load applet of Page Report Studio Frame.
PrintInHiddenFrame
Specifies to call printReport.jsp without loading applet of Page Report Studio Frame.
Reset
Resets the previous options.
View
Views this report.
Interactive
If checked, you could specify the print setup in the Print dialog.
Background
If checked, the print job will run in the background.
UseJDK1.1
If checked, you will use instance PrintJob of JDK11 to print the report.
Wait
If checked, you have to wait until the print job is finished.
SeparateLargePage
If checked, the large page will be separated into several pages automatically.
NotifyComplete
This parameter is used with the parameter wait. After the print job is finished, a box will pop up to note you, and you
could do any other work instead of keep on waiting.
Printer
Specifies the printer to implement the print job.
Page Report Studio
With JReport Server, you can obtain report results in different formats, such as HTML, PDF, and Excel.
For the HTML format, there are two viewing modes - pure HTML or Dynamic HTML. Page Report Studio
provides a dynamic report view at the client side. You can change options which enable the results to
be displayed to your requirements.
Interactive information empowers you to slice and dice your business data, to dynamically change your
view of data, and to analyze the data to glean useful business information. In short, interactive
information enables you to customize your view of business information. With JReport, any report can
be made interactive, extending the "life" of the report by allowing you to easily sort, navigate, and filter
data via Page Report Studio. This wide range of functionality, including the ability to drill down on data,
enables you to quickly derive value from your business intelligence data.
Page Report Studio provides support for many features. You can dynamically modify - filter, search,
sort and drill - reports to obtain unique and personal data views. The Page Report Studio toolbar and
interactive web objects (images, buttons, text fields, checkboxes, radio buttons, drop-down lists, etc.)
can be embedded into reports or JSPs at design time, enabling you to control, customize and navigate
report views. Page Report Studio also supports a web design feature, allowing you to create reports
using report oriented data structures, save your report, and even save your custom modifications to
existing reports.
This chapter covers the following topics to help you better understand how Page Report Studio makes
reports interactive and how you will benefit:
●
Page Report Studio window elements
●
General operations
●
Ad hoc reporting
●
Analytic reporting
●
Working with reports via URL
●
Opening multiple reports in one session
●
Tuning Page Report Studio performance
Page Report Studio window elements
The main page of Page Report Studio consists of the user information bar, menus, toolbar, page report
bar, Toolbox, Resource View panel, TOC Browser, and report area. The options for browsing or
controlling a DHTML report are as follows:
Toolbar/
Menu
File
Button
Tool Name
Description
New Page
Report Tab
Creates a new report tab to
the current page report
based on an existing
business/report cube.
New Page
Report
Creates a new page report
containing a report tab based
on an existing business/
report cube.
Open
Opens the Open Report Tabs
dialog for you to open/close
report tabs in current report.
Rename Report Opens the Rename Report
Tab
Tab dialog to give the open
report tab a new name.
Edit
Close Report
Tab
Closes the current report tab
if there is more than one
report tab open in the report;
or prompts you to close the
report if there is only one
report tab.
Delete Report
Tab
Deletes the current report
tab if there is more than one
report tab open in the report.
This command is disabled
when the last page of the
current report tab does not
display if Format Page on
Demand in the Profile >
Customize Profile > Page
Report Studio > Properties >
Advanced tab is selected.
Save
Saves the report as a report
version.
Save As
Saves a copy of the report.
Export
Exports the report result to
disk or version in various
formats.
Page Setup
Shows the Page Properties
dialog for you to specify the
page layout settings for the
report result.
Printable
Version
Shows the Printable Version
dialog for you to print the
current report result to a PDF/
HTML file.
Exit
Closes the current report.
Undo
Undoes the last operation.
View
Redo
Reverses the operation of
Undo.
Search
Shows the Search dialog for
you to find specific text.
Toolbar
Shows or hides toolbars.
User
Shows or hides the User
Information Bar Information Bar, which
displays the user name,
catalog name and report
name.
Insert
Toolbox
Shows or hides the Toolbox
panel which allows you to
insert a component into the
report.
Resource View
Shows or hides the Resource
View panel, with which you
can add cube elements to
your report and create
dynamic resources to use
them in your report.
TOC Browser
Shows or hides the TOC
Browser, with which you can
navigate the report data.
Editing Marks
Shows or hides editing marks
(dashed outlines for objects
and report body). If the
option is unselected, the
editing mark will not be
shown when a report object
receives focus, and report
objects cannot be moved or
resized.
Turn To
Provides a submenu for you
to turn the report pages.
Refresh
Runs the report using
previously provided
parameters. The Refresh
operation fetches the data
again.
Zoom
Shows the Zoom dialog for
you to set a zoom ratio for
the report page.
Options
Shows the Options dialog for
you to set the skin and unit
for Page Report Studio, and
to customize toolbars.
Show Grids
Shows grids in the report
area.
Snap to Grids
Snaps an object to grids
when you move it by
dragging and dropping in the
report area. If this option is
enabled, aligning objects will
be made easier. To
temporarily override the
setting, press the ALT key as
you move an object.
Label
Inserts a label into the report.
Image
Inserts an image into the
report.
Report
Banded Object
Inserts a banded object into
the report.
Table
Inserts a table into the report.
Crosstab
Inserts a crosstab into the
report.
Chart
Inserts a chart into the
report.
Parameter
Control
Inserts a parameter control
into the report.
Parameter
Form Control
Inserts a parameter form
control into the report.
Filter Control
Inserts a filter control into
the report.
Navigation
Control
Inserts a navigation control
into the report.
Special Fields
Inserts special fields into the
report.
Query Filter
Applies a filter to the
business/report cube used by
certain component.
Filter
Filters the report records
according to the filter criteria
you specify.
Sort
Sorts the report records or
groups in ascending or
descending order on the
fields you select.
To Chart
Converts a crosstab into a
chart.
To Crosstab
Converts a chart into a
crosstab.
Rotate Table
Rotates a table to switch its
appearance between the
horizontal and vertical layout
modes.
Rotate Crosstab Rotates a crosstab to
exchange the columns and
rows in the crosstab in order
to create a different view of
the crosstab.
Merge
Merges selected tabular cells
into one.
Split
Splits a tabular cell into the
specified number of rows and
columns.
Language
Allows you to specify the
language in which to display
the report. Available only
when Enable NLS is checked
in the Profile > Customize
Server Preferences >
Advanced panel on the
JReport Console page.
Max Records
Allows you to specify the
maximum number of records
retrieved by all components
in the report.
Help
Standard
Toolbar
View Toolbar
Use Dynamic
Formula in
Property
Allows you to apply dynamic
formulas to control object
properties.
Style
Allows you to apply a style to
the report.
Change
Parameters
Allows you to change the
parameter values in the
report.
User's Guide
Opens Page Report Studio
User's Guide.
Jinfonet
Software Home
Page
Connects to Jinfonet
Software Home Page.
Technical
Support
Accesses Jinfonet Technical
Support.
About Page
Report Studio
Shows product information
about Page Report Studio.
New Report
Tab
Creates a new report tab
based on an existing
business/report cube.
Open
Brings out the Open Report
Tabs dialog for you to open/
close report tabs in current
report.
Save
Saves the report as a report
version.
Save As
Saves a copy of the report.
Export
Exports the report result to
disk or version in various
formats.
Printable
Version
Shows the Printable Version
dialog for you to print the
current report result to a PDF/
HTML file.
Undo
Undoes the last operation.
Redo
Reverses the operation of
Undo.
Delete
Deletes the selected object.
Toolbox
Shows the Toolbox panel for
you to insert a component
into the report. Click it again
to hide the Toolbox.
Resource View
Shows the Resource View
panel, with which you can
add cube elements to your
report and create dynamic
resources to use them in
your report. Click it again to
hide the Resource View panel.
Filter
Shows the Filter dialog, with
which you can filter the
report records according to
the filter criteria you specify.
Analysis
Toolbar
Font format
buttons
Page
navigation
buttons
Sort
Shows the Sort dialog, with
which you can sort the report
records or groups in
ascending or descending
order on the fields you select.
Search
Shows the Search dialog for
you to find specific text.
Zoom
Enables you to enlarge or
reduce the size of the report.
Rotate
Rotates a crosstab or rotates
a table.
Chart Type
Lists all available chart types
for you to change the type of
a selected chart.
Style
Allows you to apply a style to
the report.
Font Face, Font
Size
Changes the face and size of
the selected font. Available
only when a label or field is
selected.
Bold, Italic,
Underlined
Makes the selected font in
bold, italic or underlined
style. Available only when a
label or field is selected.
Left, Center,
Right
Makes the selected font left,
center or right aligned.
Available only when a label
or field is selected.
Max Records
Allows you to specify the
number of records retrieved
by all components in the
report.
Page Number
Displays the current page
number. You can also input a
page number in the page box
and press Enter on the
keyboard to go to that page.
First
Goes to the first page of the
current report tab.
Previous
Goes to the previous page.
Next
Goes to the next page.
End
Goes to the last page.
Go To dropdown list
Go To
Goes to the selected report
tab or to the selected report
tab level.
If a report contains several
reports tab, you can use this
list to switch among the
report tabs. Or, after you
perform some going or
drilling actions on a report
tab, the structure of the
report tab will be displayed in
the list in a hierarchical view,
with which you can return to
any level of the report tab
easily.
When the Page Report Studio
window is not maximized in
Interactive View mode, the
button will be displayed on
the toolbar, by clicking which
you can get all the other
toolbar commands the small
window hasn't enough space
for.
More
Commands
Shortcut Menu
Language
Specifies the language in
which to display the report.
Available only when Enable
NLS is checked in the Profile
> Customize Server
Preferences > Advanced
panel on the JReport Console
page.
Filter
Provides submenu items for
filtering the data in a banded
object/table or removing the
filtering.
Sort
Provides submenu items for
sorting records on the
selected field in ascending/
descending order, or
removing the sorting.
Drill Down
Drills data to a lower
dimension according to
predefined hierarchies.
Drill To
Enables you to obtain a
different view of data by
switching among dimensions.
Drill to By Value Allows you to filter data
based on dimensions while
also obtaining a more
detailed view of the data.
Drill Up
Drills data to a higher
dimension according to
predefined hierarchies.
Go To
Goes to any group to show
its record information.
Go Up
Goes up one group level to
show the records of a higherlevel group.
Go Down
Goes down one group level
to show the records of a child
group.
Go to Detail
Goes to the details of a
group.
Conditional
Formatting
Enables you to add
conditional format to the
currently selected field.
Search
Shows the Search dialog for
you to search the report
result for some text.
Query Filter
Applies a filter to the
business/report cube used by
the specified data component.
Refresh
Re-fetches data of the
specified data component.
Properties
Shows a dialog for you to
define the object's properties.
Notes:
●
●
●
Page Report Studio has two view modes: Basic View and Interactive View, and the toolbar and menu
commands that are available in each mode vary. Administrators can specify the default mode that
will be applied when a report is opened in Page Report Studio in the Profile > Customize Server
Preferences > General tab, and you can switch between the two modes by clicking the Basic View or
Interactive View link on the Page Report Studio toolbar. However, you will not be able to switch the
mode if the Show Link of Basic/Interactive View option in the Profile > Customize Profile > Page
Report Studio > Properties > Default tab is unchecked.
The options available on the Page Report Studio window are determined by the feature profile that is
selected as the default profile in the Profile > Customize Profile > Page Report Studio > Features tab
and the property setting on the Profile > Customize Profile > Page Report Studio > Properties tab
(profile has the higher priority). The default Page Report Studio profile provides full options.
The shortcut menu contents vary with the objects you right-click. The above table only lists some
typical shortcut menu items. The following sections will guide you to use the shortcut menu for any
object you may right-click.
General operations
After having opened a report in Page Report Studio, you can do the following general operations:
●
Managing report tabs
A page report can include one or more report tabs. The Go To drop-down list on the toolbar panel or
the tabs across the top of the report lists the display names of all the open report tabs in the current
report. Clicking the display name of an inactive report tab will make it active. You can manage report
tabs in a page report easily as follows:
❍
Opening and closing a report tab
In a page report, a report tab can be shown or not. To close (hide) the active report tab, click
Menu > File > Close Report Tab . If there are one or more report tabs open other than the
active report tab, the close action will hide the active report tab; in the case that the active report
tab is the only report tab open, the close action will prompt you whether or not to close the report.
To open (show) a hidden report tab, click Menu > File > Open (or the Open button
on the
Standard toolbar) to display the Open Report Tabs dialog, in which the report tabs open in the
current report are marked with a check symbol. Check the report tabs you want to open, uncheck
the ones you want to close, and then click OK.
❍
❍
Renaming a report tab
To rename a report tab, first activate it, then click Menu > File > Rename Report Tab. In the
Rename Current Report Tab dialog, specify a new display name for the report tab.
Deleting a report tab
To delete a report tab, first activate it, then click Menu > File > Delete Report Tab. The only
report tab open cannot be deleted.
Note: A JReport Live license for JReport Server is required in order to delete report tabs. If
you do not have a Live license please contact your Jinfonet Software account manager to
obtain a license.
Tip: If the administrator has specified to switch report tabs using tabs in the Page Report Studio profile
page, you can easily activate a report tab in a report by clicking the tab representing the report tab on
the report tab bar, and closing, renaming and deleting a report tab can also be accomplished by rightclicking the report tab and choosing the corresponding command from the shortcut menu.
●
Turning the report pages
a report tab includes more than one page, to turn between the report pages, you can
●
Click the First Page button
Page button
, Previous Page button
, Next Page button
, or Last
on the View toolbar.
and press Enter to go to that page.
●
Input a number into the page box
●
Click Menu > View > Turn To and then click the corresponding command on the submenu.
●
Use the scrollbar or mouse wheel to scroll up/down the report tab.
Navigating through the report data
u can use the TOC Browser to navigate through a report tab. To show the TOC Browser, click Menu >
ew > TOC Browser.
●
the TOC Browser, expand the Report node, select a component or a node with the group value that you
nt to browse to. The page that contains the component or the matching data will then be shown.
e table of contents on the TOC Browser is organized into a tree structure. The root node represents the
port tab that you are currently viewing. The component names indicate components in the report tab. The
oup values show hierarchical groups.
r report tabs designed in JReport Designer, the nodes displayed on their TOC tree as well as the format of
e TOC tree can be customized. For details, refer to Showing components in a TOC tree in the JReport
signer User's Guide.
Refreshing the report result
fetch the data of the current report again, you can click Menu > View > Refresh.
●
Applying a style
tyle can be applied to a report in order to change its appearance and characteristics. You can create and
up your own styles in JReport Designer. When you publish your reports to JReport Server, you can
lude these custom styles with the published reports. When you run a report, the style feature will be
abled and you can select a style to apply to the report.
●
●
Applying a style to a report
To apply a style to a report, make sure nothing is selected in the report, then click Menu > Report >
Style and select the required one from the submenu, or select the required style from the style drop-
down list
on the toolbar. When a style is applied to the whole report, all
omponents in the report will take a uniform appearance.
Applying a style to a data component
The data component (banded objects, crosstabs, charts, and tables) in a report can take a different style
of its own. To apply a style to a data component, select it and then click Menu > Report > Style and
elect the required one from the submenu, or select the required style from the style drop-down list
●
on the toolbar, or right-click the component and select Apply Style from
he shortcut menu to select the required style in the Apply Style dialog. If the data component is
ontained in a banded object (for a chart, in a table also), you can also select the Inherit Style option to
make it inherit the style of its parent data component.
wever, if there is only one style available to the report, this style will be applied to the report by default,
which case, you will find that all these style related commands are hidden.
●
Changing the report parameter values
here are parameters in the current report, you can change the parameter values at runtime. To do this:
1. Click Menu > Report > Change Parameters to display the Report Parameters dialog.
2. Specify the value for each parameter. For how to specify the value, refer to Report Parameters
dialog.
3. Click OK to run the report with the specified parameter values.
u can also use parameter web controls to dynamically change the parameter values of a report at
ntime. For details, see Applying web controls.
Opening links
hen a page report is developed with links in JReport Designer, which refer to locations specified by URLs,
mail addresses or other reports, you can click the links' trigger objects in Page Report Studio to open the
ks. However, if the click priority of the link action is not specified to be the highest at report design time,
u have to right-click on the trigger objects and click the corresponding link item on the shortcut menu to
en the links. For example, if a trigger object is linked with a detail report, you need to right-click the
ect and select Detail Report from the shortcut menu to open the detail report. Meanwhile, when opening
e detail report, you may be prompted to provide encoding and DB security information before the report
ult is produced. Click OK in the prompted dialog if you want to run a detail report using the same
coding and DB security settings as that of the master report.
●
Note: When opening a link report or detail report, a "link path", which tracks the linking actions, will be
displayed in the Go To drop-down list on the navigation bar if the link report or detail report is opened
in the current window. Clicking an item in the list will switch to the corresponding report.
●
Undoing/redoing actions
u can undo or redo some actions by clicking Menu > Edit > Undo or Redo (or the Undo button
do button
or
on the Standard toolbar).
●
Configuring Page Report Studio features
e JReport Administration page provides default settings for you to use Page Report Studio features, and
ntrols whether the settings on the JReport Console page can be configured. A user playing the
dministrator" role may change the settings in the JReport Administration page so as to enable or disable
me features. Then you can configure Page Report Studio preferences on the JReport Console page, that is,
u can decide whether or not to enable the features which have been enabled on the JReport
ministration page. After you have made changes to Page Report Studio settings on the JReport Console
ge and saved them, Page Report Studio features available for you will be consistent with your new
tings on the JReport Console page. For details, see Customize Profile.
●
Setting Page Report Studio options
ge Report Studio allows you to set the skin and customize toolbars. To do this:
1. Click Menu > View > Options (or right-click anywhere on the toolbar area and select Options
from the shortcut menu).
2. In the Option tab, set the skin of Page Report Studio user interface.
3. In the Customize tab,
❍
To modify a toolbar, select it in the Current Toolbar box, remove those unnecessary items from the
Selected Tools box, and add required tools from the Available Tools box. Click
order of the tools on the toolbar.
❍
❍
or
to adjust the
To add a toolbar, click
to show the New Toolbar Name dialog, then specify the toolbar name,
click OK to return to the Options dialog, and set the tools for the new toolbar.
To delete a toolbar, select it and click
.
4. To load the default settings, including the skin, and the three built-in toolbars, namely Standard,
View, and Analysis, click the Restore Defaults button.
5. Click OK to apply the settings.
Tip: To close a toolbar, right-click anywhere on the toolbar area, then on the shortcut menu, select the
item corresponding to the toolbar name. You can also do this to open an invisible toolbar, such as a
newly-created one. The open/close toolbar operation can also be achieved by clicking the
corresponding item on the Toolbar submenu of the View menu.
●
Showing/hiding user information
e User Information bar shows the current user name, catalog path and name, and report path and name.
u can click Menu > View > User Information Bar to show or hide the bar.
Tip: Administrators can make this bar open by default. To do this, log onto the JReport Administration
page, click Profile on the system toolbar and select Customize Profile from the drop-down menu. Go to
the Page Report Studio > Properties > Default tab, and then check the User Information Bar
option.
●
Showing/hiding editing marks
Page Report Studio, you can use editing marks (dashed outlines of objects) for purposes such as aligning,
ving and resizing. By default, the editing marks are shown only when you create a new blank report in
ge Report Studio. You can click Menu > View > Editing Marks to switch the status of the editing marks
required.
●
Tuning report page magnification
on the View
u can zoom in or out the report page by selecting a magnification from the Zoom list
olbar. You can also click Menu > View > Zoom to show the Zoom dialog, and then specify the
gnification.
●
Asking for help
any time, you can click Menu > Help > User's Guide to open the index page of Page Report Studio
er's Guide. Furthermore, you can click the Help button in any dialog to show the help about the dialog.
u can also use the Help menu to open the User's Guide and access Jinfonet Software website for more
ormation.
Setting up the page
set up the report page, click Menu > File > Page Setup. In the Page Properties dialog, specify the page
pe, the orientation, and the margins as required.
●
●
Printing the report result
u can print the report result to a PDF/HTML file. To do this, click Menu > File > Printable Version (or
e Printable Version button
on the Standard toolbar). In the Printable Version dialog, specify the
tings as required and then click OK. The PDF/HTML result file will be opened in an associated program
h which you can print the result to a printer.
●
Exiting the report
you want to close the current report and release the resources, just click Menu > File > Exit (or the Exit
tton
which is always on the upper right corner of the Page Report Studio window, or the close button
the browser window). Closing the only report tab open will also prompt you whether or not to close the
port. In case that you have modified the report without saving it, Page Report Studio will prompt you to
ve the report. If you have changed the sort and/or filter criteria, you can check Sort and/or Filter in this
log to save these changes with the report. Click Yes to save the report and close the report.
Ad hoc reporting
Ad hoc reporting allows a business analyst or end user to create a new report, add new objects to an
existing report, modify report objects, and save the report or report result. These tasks are performed
in the JReport Server environment and do not require use of JReport Designer.
This section describes the following ad hoc reporting tasks:
●
Creating a report tab
●
Adding report objects
●
Applying web controls
●
Making simple modifications to report objects
●
Saving the report
●
Exporting the report result
Creating a report tab
In Page Report Studio, you can create a new report tab based on a predefined business/report cube to the current page report.
You can also create a new page report containing one report tab and then add report tabs to it. However, the reports created on
business/report cubes in Page Report Studio cannot be edited in JReport Designer any further.
To create a report tab:
1. In a Page Report Studio window, click Menu > File > New Page Report Tab (or the button
toolbar) to display the New Report Tab dialog.
on the Standard
If you click Menu > File > New Page Report, the New Page Report dialog will appear for you to create a page report
with the first report tab in it.
2. Specify the title of the report tab as required in the Report Title text box.
3. In the Choose Report Layout box, select the required layout with which you want to create the report tab.
4. Click OK to create the report tab.
❍
❍
If Blank is selected as the layout, a report tab which is blank will be created. You can then use the Toolbox and the
Resource View panels to add objects and cube elements to the report tab.
If you select the layout as Banded, Table, Chart, or Crosstab, the corresponding report wizard will then be displayed.
Specify the settings according to your requirements.
Also, on the JReport Console > Resources page, you can directly create a new page report (containing a report tab) in a folder
into which one or more catalogs containing some business/report cubes have been published. To do this:
1. Open the folder and select the catalog for the new page report from the Catalog drop-down list.
2. On the task bar of the Resources page, click New > Report.
3. In the Select Report Type dialog, check the option Page Report and click Ok.
4. In the New Page Report dialog, create the page report containing a report tab as required.
Notes:
●
●
A JReport Live license for JReport Server is required in order to use this feature. If you do not have a Live license please
contact your Jinfonet Software account manager to obtain a license.
Before you can create a report tab in Page Report Studio, you need to first make sure that the catalog corresponding to the
current page report contains one or more business/report cubes and that the Pop-up Blocker is not enabled on your web
browser.
The following topics show in detail how to create a report tab from particular layouts:
●
Creating a banded report
●
Creating a table report
●
Creating a chart report
●
Creating a crosstab report
Creating a banded report
A banded object is a kind of component that can present grouped data and detailed data, and is
composed of several banded panels with which you can easily organize data fields and other elements.
To create a banded report, follow the steps below:
1. Take steps 1 and 2 in Creating a report tab.
2. Select Banded as the layout and click OK to display the Banded Wizard.
3. In the Data screen, select the business/report cube in the current catalog, on which the banded
object will be built.
4. In the Display screen, add the required fields from the Resources box to be displayed in the
banded object. Modify the display name of any added field if necessary.
5. In the Group screen, add the dimension objects
as the grouping criteria, then specify the
sorting direction of each group in the Sort column.
6. To add summaries, go to the Summary screen. Select the group to which the summary will be
applied, then add a measure object
as the summary field.
7. In the Query Filter screen, specify the filter you want to apply to the business/report cube.
8. In the Style screen, apply a style to the banded object.
9. Click Finish to create the report.
See also Banded Wizard for details about options in the wizard.
Note: If there is only one cube in the current catalog, this cube will be used to create the report by
default, and the Data screen will be hidden from the wizard. This is the same case when there is only
one style available to be applied to the report.
Creating a table report
Tables give you great control over how to present data, including placing fields, grouping them, and
sorting them. A table is composed of row and columns, and each contains several cells. With such a
structure a table is a good way to show any two-dimensional dataset.
To create a table report, follow the steps below:
1. Take steps 1 and 2 in Creating a report tab.
2. In the Choose Report Layout box, select the desired table type, then click OK to display the Table
Wizard.
❍
❍
❍
❍
Table (Group Above)
Creates a table with group information above the detail panel.
Table (Group Left)
Creates a table with group information left to the detail panel.
Table (Group Left Above)
Creates a table with group information left above the detail panel.
Summary Table
Creates a table with only group and summary information.
3. In the Data screen, select the business/report cube in the current catalog, on which the table will
be built.
4. In the Display screen, add the required fields from the Resources box to be displayed in the table.
Modify the display name of any added field if necessary.
as the grouping criteria, then specify the
5. In the Group screen, add the dimension objects
sorting direction of each group in the Sort column.
6. To add summaries, go to the Summary screen. Select the group to which the summary will be
applied, then add a measure object
as the summary field. For the Group Left table, you can
use the Row and Column columns to control the position of the summary field in the table.
7. In the Query Filter screen, specify the filter you want to apply to the business/report cube.
8. In the Style screen, apply a style to the table.
9. Click Finish to create the report.
See also Table Wizard for details about options in the wizard.
Note: If there is only one cube in the current catalog, this cube will be used to create the report by
default, and the Data screen will be hidden from the wizard. This is the same case when there is only
one style available to be applied to the report.
Creating a chart report
A chart organizes and graphically presents data in a way that makes it easy for end users to see
comparisons, trends, and patterns in data. It represents the report data in a visually straightforward
form. A chart is based on the chart platform. On the platform, the chart paper, the legend, and labels
make up the chart. You can create a chart that contains only simple DBFields, or a complicated chart
that contains DBFields, groups, summaries, and even formulas. Normally, DBFields, summaries, and
formulas in a report are represented in a chart using chart data markers, and groups are used to
produce category names and data series names. DBFields can also be used as category names.
For details about the chart types JReport supports, see Chart types in the JReport Designer User's
Guide.
For how charts present data, see How data is represented in a chart in the JReport Designer User's
Guide.
For the elements that compose a chart, see Chart elements in the JReport Designer User's Guide.
To create a chart report, follow the steps below:
1. Take steps 1 and 2 in Creating a report tab.
2. Select Chart as the layout and click OK to display the Chart Wizard.
3. In the Data screen, select the business/report cube in the current catalog, on which the chart will
be built.
4. In the Type screen, specify the chart type as required.
A default chart type exists in the Chart Type Groups box. To replace it with another one, select a
chart type from the Chart Type box. The thumbnails of the subtypes in this type will then be
displayed in the Subtype box. Select the required subtype to replace the default chart type.
If you want to create a combo chart, click <Add Combo Type> of Primary Axis or Secondary Axis
in the Chart Type Groups box, and an additional subtype will be added. To replace the additional
subtype, select it, then specify the required type and subtype respectively in the Chart Type and
Sub Type boxes.
To add more subtypes, repeat the procedures. To remove a subtype, select it and click
.
5. In the Display screen, select a dimension object
in the Resources box and add it to the
Category or Series box, the data of which will be displayed on the corresponding axis. Select a
subtype in the Show Values box, then add a measure object
data of the subtype.
or an additional value
as the
To add an additional value to a subtype:
a. Select the subtype in the Show Values box.
b. In the Resources box, expand the Additional Values node, then select Constant Value/
Average Value.
c. Click
beside the Show Values box. The Edit Additional Value dialog appears.
d. In the Name text box, specify the display name for the constant/average value.
e. Input the constant value with numeric type in the Value text box, or select a field based on
which the average value will be calculated from the Based On drop-down list.
f. Click OK, and the defined constant/average value will be added to the subtype.
If you want to further modify a constant/average value, select the value in the Show Values
box, then click
. In the Edit Additional Value dialog, edit the value as required.
You can add more than one measure object or additional value to a subtype. Each added subtype
shall have at least one measure object or additional value.
6. If you want to define the sort order and Select N condition on the category/series axis of the
chart, click the Order/Select N button below the Category/Series box, then define the condition
in the Order/Select N dialog.
To define a sort order and Select N condition on the category/series axis:
a. In the Order box of the Order/Select N dialog, specify in which order values on the category/
series axis will be sorted.
b. In the Select N box, specify the Select N condition to All, Top or Bottom. If All is selected, all
category/series values will be shown in the chart; if Top or Bottom is selected, the text field
next to it will be enabled and you can specify an integer here, which means that the first or
last N category/series values will be shown in the chart.
c. Check the Based On checkbox and specify values for the two drop-down lists that follow
according to your requirement.
If Based On is unchecked, the order of the first or last N category/series values will be based
on what you specify in the Order box of the dialog; if you check it, the order will be based on
values of the summary field and the sort direction you specify in the drop-down lists next to
the Based On checkbox.
d. If you have selected Top or Bottom from the Select N drop-down list, you can check the
Other checkbox and the type a character string in the next text field, so that the category/
series values beyond the first or last N range will be merged into the group with the name as
that character string.
e. Click OK to accept the settings.
7. In the Query Filter screen, specify the filter you want to apply to the business/report cube.
8. In the Style screen, apply a style to the chart.
9. Click Finish to create the report.
See also Chart Wizard for details about options in the wizard.
Note: If there is only one cube in the current catalog, this cube will be used to create the report by
default, and the Data screen will be hidden from the wizard. This is the same case when there is only
one style available to be applied to the report.
Creating a crosstab report
A crosstab summarizes data and presents the summaries in a compact row and column format.
To create a crosstab report, follow the steps below:
1. Take steps 1 and 2 in Creating a report tab.
2. Select Crosstab as the layout and click OK to display the Crosstab Wizard.
3. In the Data screen, select the business/report cube in the current catalog, on which the crosstab
will be built.
4. In the Display screen, select a dimension object
and click
or
to add it to the Columns
or Rows box as a group field. Select a measure object
and click
to add it to the
Summaries box as an aggregate field. Repeat this to add more group/aggregate fields.
5. In the Display Name column, edit the display names of the added group fields or aggregate fields
if required. These will label the rows, columns and summaries when the report is displayed. By
default these are blank and no labels will be created.
6. In the Sort column, specify the sorting manner for the group fields.
. To adjust the order of the
7. If you want to remove any group/aggregate field, select it and click
group/aggregate fields, select a group/aggregate field and click
or
.
8. In the Query Filter screen, specify the filter you want to apply to the business/report cube.
9. In the Style screen, apply a style to the crosstab.
10. Click Finish to create the report.
See also Crosstab Wizard for details about options in the wizard.
Note: If there is only one cube in the current catalog, this cube will be used to create the report by
default, and the Data screen will be hidden from the wizard. This is the same case when there is only
one style available to be applied to the report.
Adding report objects
For a newly-created or an existing report, if the corresponding catalog contains business/report cubes,
then you can add labels, images, banded objects, tables, crosstabs, charts, special fields and web
controls to the report.
Object placement
Objects can be placed within banded objects, tables, tabulars, as well as onto an empty area of a
report. The following table lists the report areas that are valid targets for the various objects, listed on
the left.
Report Layout Area
Page
Header/
Footer
Report
Header/
Footer
Report
Body
Banded
Detail
Banded
Page
Header/
Footer
Banded
Header/
Footer
Banded
Group
Header/
Footer
Table
Cell
Tabular
Cell
Banded
object
Y
N
Y
Y
Y
Y
Y
N
Y
Chart
Y
Y
Y
Y
Y
Y
Y
N
Y
Crosstab
Y
Y
Y
Y
Y
Y
Y
N
Y
Table
Y
Y
Y
Y
Y
Y
Y
N
Y
Dimension
object
Y
Y
Y
Y
Y
Y
Y
Y
Y
Detail
information
object
Y
Y
Y
Y
Y
Y
Y
Y
Y
Measure
object
N
N
Y
N
N
Y
Y
N
N
Formula
Y
Y
Y
Y
Y
Y
Y
Y
Y
Label
Y
N
Y
Y
Y
Y
Y
Y
Y
Object
Special field
Y
N
Y
Y
Y
Y
Y
Y
Y
Image
Y
N
Y
Y
Y
Y
Y
Y
Y
Web control
Y
Y
Y
Y
Y
Y
Y
N
Y
To add an object into a report:
1. Click Menu > Insert, then click the command corresponding to the object you want to add.
2. Point to the destination where you want the object to be added, and then click the mouse button.
❍
❍
❍
❍
If you specify to add a label, a label will be inserted there. Edit the text of the label and format it
according to your requirements.
If you specify to add an image, the Insert Image dialog will be displayed. Specify the source of
the image as required (for details, see Insert Image dialog).
If you specify to add a banded object, table, crosstab, or chart, the corresponding report wizard
will be displayed. Specify the settings in the wizard according to your requirements (for details,
see the specific topic in Creating a report tab).
If you specify to add a special field, the special field will be inserted there (for details about the
usage of each special field, see Special fields in the JReport Designer User's Guide).
❍
❍
If you specify to add a parameter control, parameter form control, or filter control, the
corresponding insert control dialog will be displayed. For how to specify the settings in the dialog
and the usage of the web control, see Applying web controls.
If you specify to add a navigation control, a navigation control will be inserted there. For the
usage of the navigation control, see Applying web controls.
Alternatively, you can also use the Toolbox panel to add objects other than special fields into a report
by dragging them from the panel to the destination. However, in order to use the Toolbox panel to add
components, you should make sure that this ad hoc feature is enabled in the specified Page Report
Studio feature profile. This setting can only be made by administrators.
Note: A JReport Live license for JReport Server is required in order to use this feature. If you do not
have a Live license please contact your Jinfonet Software account manager to obtain a license.
Applying web controls
In Page Report Studio, these four types of web controls can be applied: parameter control, parameter
form control, filter control, and navigation control. This section describes each of the web controls and
how to use them.
Note: A JReport Live license for JReport Server is required in order to use this feature. If you do not
have a Live license please contact your Jinfonet Software account manager to obtain a license.
Using parameter control to specify a parameter to a report
A parameter control is a web control that is bound with a parameter used by the current report. By
specifying values to the parameter in a parameter control, you can pass the parameter values to JReport
and run the report with the specified values.
Cascading parameters cannot be used in parameter controls. If you want to do this, use parameter form
controls instead.
To insert a parameter control and use it to specify a parameter to a report:
1. Do either of the following:
❍
❍
Click Menu > Insert > Parameter Control, then point to the destination where you want to
add the parameter control and click the mouse button.
Drag Parameter Control from the Toolbox panel to the destination in the report.
The Insert Parameter Control dialog is displayed.
2. Select the parameter you would like to add to the parameter control, then click OK.
3. A parameter control will be added into the report. Specify the value for the parameter. You may
specify the value in one of these ways.
4. Once the value in the parameter control changes, the report will rerun with the new parameter
value.
Note: If the specified parameter is no longer used in the report, the parameter control will become
invalid.
Using parameter form control to run reports
A parameter form control is a web control that is bound with the parameters used by the current report
or other reports. By specifying values to the parameters in a parameter form control, you can make the
reports run with the specified parameter values.
To insert a parameter form control and use it to run report:
1. Do either of the following:
❍
❍
Click Menu > Insert > Parameter Form Control, then point to the destination where you want
to add the parameter form control and click the mouse button.
Drag Parameter Form Control from the Toolbox panel to the destination in the report.
The Insert Parameter Form Control dialog is displayed.
2. Specify the target reports to run using the parameter form control.
❍
❍
To run the current report, select Current Report, then specify the parameters used to run the
report from the Select Parameters box.
To run other reports, select Others, then select the reports you want to run. If all the selected
reports contain no parameters, you cannot finish the dialog.
3. Specify whether to include the Submit button in the parameter form control. If Submit is included,
it is used to submit the parameter values you specified in the parameter form control. If Submit is
not included, once you change the values of a parameter in the parameter form control, the new
values will be applied automatically.
4. Click OK in the dialog to save the changes.
The parameter form control is now inserted in the report. It lists the selected parameters for the
current report or lists all parameters used by the specified reports.
5. In the parameter form control, specify values of the listed parameters. You may specify the values
in these ways.
6. Click the Submit button to run the current report or the specified reports if the button is available.
If there is no Submit button, the change of values in the parameter form control will trigger report
rerunning.
Note: If you save or publish a report containing a parameter form control to another directory, the
reports that you bind the parameter form control with will not be saved or published along with the
report.
Using filter control to filter report data
A filter control is used to filter one or more data components in a report, which refer to tables, banded
objects, charts, and crosstabs. For how a filter control works, see Filtering scenarios.
To insert a filter control and use it to filter report data:
1. Do either of the following:
❍
❍
Click Menu > Insert > Filter Control, then point to the destination where you want to add the
filter control and click the mouse button.
Drag Filter Control from the Toolbox panel to the destination in the report.
The Insert Filter Control dialog is displayed.
2. From the resource list, select the fields of the same data type to bind to the filter control.
To filter components created from the same data source, select a field in the data source.
To filter components created from different data sources, find a common field these data sources
contain, then select the field in each of the data sources.
3. The Apply To drop-down list provides the components involving the selected fields. Select the
components which you want to filter.
4. When done, click OK.
The filter control is inserted in the report. It lists all values of the specified fields. You can select
one or more values to apply.
After inserting filter controls in the report, you can also insert a navigation control for undoing/redoing
the value selection in the filter controls. For details about the usage of navigation control, see Using
navigation control to undo/redo value selection in filter controls.
Managing a filter control
After right-clicking on the title bar of a filter control, these options are available for managing the filter
control.
●
●
Properties
Opens the Filter Control Properties dialog for editing the properties of the filter control.
Search
Displays the quick search toolbar right above the filter control which enables you to search values in
the filter control. You can also click the button
quick search toolbar.
on the title bar of the filter control to launch the
The following are details about the usage of the quick search toolbar:
❍
❍
❍
Text field
Type in the text you want to search for in the text field and the matched text will be highlighted
among the field values.
X
Closes the quick search toolbar. You can also click outside of the quick search toolbar to achieve
this.
Lists the advanced options.
■
■
Highlight All
Specifies whether to highlight all matched text.
Match Case
Specifies whether to search for text that meets the case of the typed text.
■
●
Match Whole Word
Specifies whether to search for text that matches a whole word and ignore partial word matches.
❍
Highlights the next matched text.
❍
Highlights the previous matched text.
Clear
Cancels the selection of values in the filter control. You can also use the button
cancel the selection. This operation can be undone/redone.
●
●
●
on the title bar to
Sort
Sorts the values in the filter control in the ascending or descending order.
Delete
Removes the filter control from the report and the filter you created with the filter control will be
removed from the report too. You can also use the close button on the title bar to remove the filter
control.
Hide
Hides the filter control.
Cascading relationship between filter controls
When there are filter controls that apply to the same data components, and when these controls' fields
have cascading relationship, the cascading relationship will be revealed when you select values in the
controls.
For example, there is a filter control based on the field Country, a filter control on City, and another on
State. The first two share one table while the third shares nothing with the other two. In this case,
Country and City values will show cascading relationship, but State values will not participate. You select
USA in the Country filter control, the values in the City filter control will change as follows if the control
has scrollbar: the cities belong to USA are displayed in the upper area of the filter control, and the other
cities are put in the lower area and grayed out. For the case that the City filter control has no scrollbar:
all the values remain their positions and the values not belonging to USA are grayed out. In both cases
all the values are selectable. But the State values remain as before, since the selection of them will not
affect the data components that the Country and City filter controls control.
Using navigation control to undo/redo value selection in filter controls
A navigation control can be considered as an accessorial control for filter controls and is used to deal
with the value selection operations in all the filter controls in the same report.
To insert a navigation control into a report, do either of the following:
●
●
Click Menu > Insert > Navigation Control, then point to the destination where you want to add
the navigation control and click the mouse button.
Drag Navigation Control from the Toolbox panel to the destination in the report.
A navigation control is a combination of three buttons:
●
Back
Goes back to the previous value selection status and refreshes the report data accordingly.
●
●
Clear
Removes all the value selection histories and all the filter conditions based on the selections, and
refreshes the report data accordingly.
Forward
Goes forward to the next value selection status and refreshes the report data accordingly.
Making simple modifications to report objects
By virtue of Page Report Studio's powerful ad hoc functions, you can make simple modifications to
report objects at runtime while viewing the report in Page Report Studio.
Note: Except for showing/hiding objects, a JReport Live license for JReport Server is required in order
to use all the other features introduced in this article. If you do not have a Live license please contact
your Jinfonet Software account manager to obtain a license.
Moving an object
A table, banded object, chart, crosstab, tabular, or image, can be easily moved to a new position. What
appearing at its upper left corner
you need to do is click anywhere in the object, then drag the icon
to the destination. After Page Report Studio has finished processing, the object will be redrawn in the
new location.
For other objects, select it and move it to the new position.
Notes:
●
●
Before you can move any object in a report, you need to first make sure that the Page Report Studio
window is in the Interactive View mode.
For reports designed in JReport Designer, only the objects whose Position property value is absolute,
and the DBFields or labels which have been defined as a cube element can be moved in Page Report
Studio.
Resizing an object
To resize an object, click anywhere in the object, when the icon
appears at its upper left corner,
click the icon to select the object, then you will see that it is surrounded by a rectangle with three
resizing handles. Point to a handle, when the mouse pointer turns to a double-headed arrow, you can
drag the handle to resize the object.
To resize a panel in a banded object, select it and drag the resizing handle to the desired position.
To adjust the width/height of a column/row in a table, point to the right/lower boundary of the column/
row, when the mouse pointer becomes a horizontal/vertical double-headed arrow, drag the handle and
the width/height of the column/row will change. This will also resize all cells in the column or row.
For a crosstab, you can resize its rows and columns the same as you do with a table.
For a tabular, point to the boundary between two cells and the mouse pointer will become a doubleheaded arrow, you can then drag the boundary to adjust the size of the related cells.
To change the width and height of a field, click any value of this field to select it, then drag the right or
lower resizing handle on its borders to a new position, and the width or height of the field will change.
You can also do this for any label.
Notes:
●
When resizing table rows:
❍
❍
If you resize the table header, only the height of the header will be changed. However, when you
resize any row except the header, the height of all rows in the table will be changed at the same
time.
If there are some groups in a table and the height of one group row is changed, the other group
rows will not be resized.
When resizing crosstab columns/rows:
●
❍
If you resize the horizontal/vertical header of a crosstab, other rows/columns will not be affected.
❍
If you resize the total column/row of a crosstab, other columns/rows will not be affected.
Hiding/showing an object
To hide a table, banded object, chart, crosstab, or tabular, click on the object, when the icon
appears at its upper left corner, right-click on the icon and then select Hide from the shortcut menu.
For other objects such as text boxes, drop-down lists, fields, and labels, right-click it and then select
Hide to hide it.
To show a hidden object, right-click the object containing it, then on the shortcut menu, select the
object name from the Show submenu.
Splitting and merging cells in a tabular
Adjacent cells in a tabular which can form a rectangle may be merged into one cell.
To merge adjacent cells, select them one by one while holding the Ctrl key, then click Menu > Report
> Merge, and these cells will be merged into one cell.
To split a cell:
1. Select the cell and click Menu > Report > Split.
2. In the Split dialog, specify the number of rows and columns.
3. Click OK and the cell will be split.
Modifying object properties
Page Report Studio allows you to modify object properties with the corresponding properties dialog.
●
●
●
To format the properties of any object in a report, right-click on the object and select Properties
from the shortcut menu. If it is a table, crosstab, chart, banded object, or tabular, click anywhere on
appears at its upper left corner, right-click on the icon and click Properties on
it, when the icon
the shortcut menu. In the corresponding properties dialog, specify the settings as required. For a
table, you can also right-click any field or cell in it and select Table from the shortcut menu to show
the Table Properties dialog.
You can right-click a group header/footer panel in a banded object, and then select Group to show
the Group Properties dialog in order to define the group properties.
If you want to format the properties of the report, right-click the blank part of the report, select
Report from the shortcut menu, then in the Report Properties dialog, configure the properties as
required.
●
To set up report page properties, click Menu > File > Page Setup, then in the Page Properties
dialog, specify the settings according to your requirements.
Tip: If you just want to modify the text related properties for a field or label, for example, you want to
change the text alignment or make the text bold, you can achieve it by simply selecting the field or
label, then clicking the corresponding buttons on the toolbar.
For detailed explanation about options in the properties dialogs, refer to the specific topics in Page
Report Studio dialogs.
Deleting an object
An object can be removed from the report if it is no longer required. However, objects that are in a
subreport cannot be deleted.
●
●
To delete a table, banded object, chart, crosstab, tabular, or image, click on the object, when the
appears at its upper left corner, right-click on the icon and select Delete from the shortcut
icon
menu, or you can drag the icon outside the report page. Then, a message box will prompt, asking for
your confirmation. Click OK in the message box so as to remove the component.
For a field, you can drag any value of the field outside the report page to remove it. You can also
drag any label outside the report page to remove it. Right-clicking and then selecting Delete is
another way to achieve this.
Saving the report
You can save your report in a Page Report Studio window. To do this, click Menu > File > Save (or
the Save button
on the Standard toolbar). The Save Report Template dialog appears. The Sort
and Filter options in this dialog signify whether or not to include the sort and filter criteria when saving.
Specify the options as required, then click OK, and the report will be saved as a report version.
If the report is newly created and has not yet been saved, the Save As dialog will be displayed.
1. In the Save in section, browse to the folder where you want to save the report in the server
resource tree. The folder may be Public Reports or My Reports. You can use the button
to the parent folder.
to go
The resource table shows the resources in the current directory. Click the column names to
change the order of the report in the table list if required.
2. In the File Name box, enter the name of the report or use the default name.
3. From the File Type drop-down list, specify the type of the saved report.
4. Click the Advanced button to set the advanced settings for the report if required.
a. The catalog that the report uses is shown.
Specify the relationship between the saved report and the catalog used to run it (activated
only when Select Catalog Linked Model is checked in the Profile > Customize Profile > Page
Report Studio > Properties > Advanced tab):
■
■
Set Original Catalog as Linked Catalog into Saved Page Report
If checked, the saved report will be linked with the catalog and the saved report will run
with the catalog no matter whether the two are in the same directory. If later the catalog is
updated, the saved report will run with the latest version of the catalog.
Set Catalog Copy to Public Reports/My Reports
If checked, the catalog will be copied to the directory where the report is saved and the
saved report will run with the copied catalog.
b. If you want to save the report together with the sort and filter criteria, check Save Sort
Criteria and Save Filter Criteria correspondingly. With the criteria saved, Page Report
Studio will automatically apply them to the report the next time it is opened.
c. Optionally, input comments in the Description box as a description for the report.
5. Click OK to save the report.
To save a copy of a report, click Menu > File > Save As (or the Save As button
toolbar) to show the Save As dialog, and then do as above.
on the Standard
Notes:
●
●
●
You will not be able to save the report to some locations if you do not have the required permissions.
You need to have Write access to the directory.
If one of the report tabs in a report contains subreports, when you save the report, changes you
have made on the subreports will not be saved along with the primary report.
To find a newly saved report version, browse to select the row that the report is in on the JReport
Console > Resources page, click Tools > Version on the task bar, and then click the Report
Versions tab.
Exporting the report result
When you are satisfied with the result of the active report, you may want to export it as a result
version or as a local file to other formats.
The following topics describe exporting report results in detail:
●
Exporting the result from a Page Report Studio window
●
Exporting the result by using a JavaScript function
●
Customizing buttons for one-step exporting
●
Controlling user access to different export formats
●
Customizing warning messages
Note: If the report you are going to export is linked to another report, in the exported results, the link
will no longer be available.
Exporting the result from a Page Report Studio window
You can export the report result from a Page Report Studio window to other formats by taking the following
steps:
1. Click Menu > File > Export (or the Export button
dialog.
on the Standard toolbar) to display the Export
2. In the File Name field, specify the name of the exported result file.
3. Specify the destination of the result:
❍
❍
❍
Save to Version System: The result will be saved as a result version in JReport Server's versioning
system.
Save to File System: The web browser will prompt you to save the result file to a specified folder. If
selected, you need to provide a name for the result file in the File Name field.
View Report Result: The result will be directly opened in the web browser if the format is supported by
a plug-in of the web browser; otherwise it will prompt you to save the result file.
4. From the Select Format drop-down list, select the format in which to export the result: HTML, PDF, Excel,
Text, RTF, XML, PostScript, or Page Report Result.
5. To specify the additional setting of the selected format, click More Options.
6. From the Style Group drop-down list, select the style group you want to apply to the exported report
result. If No Style is selected, the style group property predefined for the specified export format in
JReport Designer will be applied to export the report result to that format.
7. Set the other properties for the selected format as required (for details about properties of each format,
see Export dialog).
8. Click OK to confirm.
Exporting the result by using a JavaScript function
JReport Server provides you with a JavaScript function which allows you to open the report result or
export it in a specified format. You can find this function in the file API.js in <server_install_root>
\public_html\javascript\dhtml, as shown below:
function user_oneStepExport(type, options)
The following explains this function's two arguments, type and options, in detail.
type - Specifies the export format.
●
HTML = 0
●
PDF = 2
●
PS = 3
●
RTF = 4
●
TEXT = 5
●
EXCEL = 6
●
XML = 7
options - Specifies the values of the options of each format. It is a string array whose member is of
the format "key=value". The options and their usage are listed as follows:
Description
Available Value
Default
Value
to_ver
Specifies whether or not to save the result to
version.
true, false
false
to_open
Specifies whether or not to export and open the
result file.
true, false
false
to_local
Specifies whether or not to save the result to a
local file.
true, false
false
browser
Specifies the web browser type.
0 - IE or Chrome
0
Key
HTML
1 - Firefox
imagetype
Specifies the type of the images in the result file.
0 - Decided by JReport
0
1 - GIF
2 - JPG
overflow
Specifies the overflow type.
0 - VISIBLE
0
1 - HIDDEN
2 - VERFLOWCOUNT
resolution
Specifies the HTML resolution.
Any integer between 1 and
4294967296
96
title
Specifies the title for the HTML file.
Any string
""
applet
Specifies whether or not to export chart in Java
applet format.
true, false
true
css
Specifies whether or not to embed the cascading
style sheet in the exported HTML files.
true, false
false
multi
Specifies whether or not to generate an HTML file
for each page of the report result.
true, false
false
hyperlink
Specifies whether or not to contain hyperlinks in
the HTML file.
true, false
false
pagenumber
Specifies whether or not to contain page numbers
in the HTML file.
true, false
false
drilldown
Specifies whether or not to include the drilled-down true, false
file in the exported HTML file.
false
no_margin
Specifies whether or not to remove the original
margins.
true, false
false
absolute
Specifies whether or not to make the font size fixed true, false
in the web browser.
false
to_ver
Specifies whether or not to save the result to
version.
true, false
false
to_open
Specifies whether or not to export and open the
result file.
true, false
false
to_local
Specifies whether or not to save the result to a
local file.
true, false
false
no_margin
Specifies whether or not to remove the margin.
true, false
false
simulate
Specifies whether or not the mode is to be
Simulated Printing Mode.
true, false
true
standard
Specifies whether or not to set the mode as
Standard Mode.
true, false
false
content
Specifies whether or not to contain the TOC in the
exported PDF file.
true, false
false
drilldown
Specifies whether or not to include the drilled-down true, false
file in the exported PDF file.
false
encrypt
Specifies whether or not to encrypt the report
result.
true, false
false
compress
Specifies whether or not to compress the images in
the report.
true, false
false
ratio
Specifies the percentage with which to compress
the images in the report.
Any integer between 1 to 100
20
compatibility
Specifies the encryption compatibility.
0 - Acrobat 3.0 and later
1
PDF
1 - Acrobat 5.0 and later
doc_psw
Specifies the password for opening the PDF file
when encrypt=true.
Any string
""
permi_pasw
Specifies the password for printing and editing the
PDF file when encrypt=true.
Any string
""
printing
Specifies the PDF printing mode.
0 - Prevents users from
printing the file
0
4 - Allows low resolutionprinting
2052 - Allows high-resolution
printing
changes
Defines which editing actions are allowed in the
PDF file.
0 - Prevents users from
making any changes to the file
0
1024 - Allows inserting,
deleting, and rotating pages
256 - Allows users to fill in
form fields and adding digital
signatures.
32 - Allows users to fill in form
fields and add digital
signatures and comments
40 - Allows users to do
anything except extracting
pages
2108 - Allows all
enable_copy
Specifies whether or not to allow users to copy the
file contents.
true, false
false
enable_access
Specifies whether or not to let visually impaired
users read the document with window readers.
true, false
true
to_ver
Specifies whether or not to save the result to
version.
true, false
false
to_open
Specifies whether or not to export and open the
result file.
true, false
false
to_local
Specifies whether or not to save the result to a
local file.
true, false
false
no_margin
Specifies whether or not to remove the margins in
the PS file.
true, false
false
to_version
Specifies whether or not to save the result to
version.
true, false
false
to_open
Specifies whether or not to export and open the
result file.
true, false
false
to_local
Specifies whether or not to save the result to a
local file.
true, false
false
rtf_flow
Specifies whether or not to apply a flow layout
when exporting the report to RTF.
true, false
false
no_margin
Specifies whether or not to remove the margins in
the RTF file.
true, false
false
to_ver
Specifies whether or not to save the result to
version.
true, false
false
to_open
Specifies whether or not to export and open the
result file.
true, false
false
to_local
Specifies whether or not to save the result to a
local file.
true, false
false
repeat
Specifies whether or not to replace a field value of
a record with that of its previous record if the field
value is null.
true, false
false
compress
Specifies whether or not to compress the clearance
between columns.
true, false
false
win_linebreak
Specifies whether or not to use Windows end-ofline characters.
true, false
true
normal
Specifies whether or not to generate the report
result to a standard text file.
true, false
true
PostScript
RTF
Text
quote_mark
Specifies whether or not to mark the fields in the
exported file with quotation marks.
true, false
false
head_foot
Specifies whether or not to contain all headers and
footers in the report.
true, false
true
delimiter
Specifies the delimiter.
Any single character
width
Specifies the user-defined character width.
An integer
height
Specifies the user-defined character height.
An integer
to_ver
Specifies whether or not to save the result to
version.
true, false
false
to_open
Specifies whether or not to export and open the
result file.
true, false
false
to_local
Specifies whether or not to save the result to a
local file.
true, false
false
wrap
Specifies the word-wrap setting.
0 - All Keep Existing
0
Excel
1 - All Disabled
2 - All Enabled
new_layout
Specifies whether or not to use the new layout
mode.
true, false
true
shapes
Specifies whether or not to include the shapes in
the exported file.
true, false
false
excel_2000
Specifies whether or not to export the result in
true, false
Data Format, which means only the report data will
be exported without format.
false
advanced
Specifies whether or not to apply the advanced
options.
true, false
false
header
Specifies the page header text.
Any string
footer
Specifies the page footer text.
Any string
gridline
Specifies whether or not to print gridlines when
printing the exported Excel file.
true, false
false
to_ver
Specifies whether or not to save the result to
version.
true, false
false
to_open
Specifies whether or not to export and open the
result file.
true, false
false
to_local
Specifies whether or not to save the result to a
local file.
true, false
false
only_data
Specifies whether or not to only contain the
database column information in the exported XML
file.
true, false
false
schema
Specifies the name of an existing schema file with
its full path with which to generate the XML file.
An existing schema file with its
full path.
XML
Notes:
●
●
The three options to_ver, to_open, and to_local are mutually exclusive, that is, only one of them
should be true, and the rest false. If you set two or three of them to true, JReport will only accept
the first true and treat the rest as false. If you set all three to false, JReport will consider to_open as
true.
In the string array options, the members are separated by commas (","). You can arrange the
members in any order, and omit those keys where you want to use the default value. For example,
you can define a variable html_options:
var html_options = ["imagetype=1", "resolution=120", "hyperlink=true",
"no_margin=false", "title=hello world"];
Then, you can use user_oneStepExport(0, html_options) to obtain a URL for exporting the report
result in HTML format.
●
JReport also provides the function user_downloadReport(type, options) whose usage is similar to
user_oneStepExport.
Customizing buttons for one-step exporting
Seven buttons are provided for one-step exporting. They are Export to PDF, Export to Excel, Export to
RTF, Export to HTML, Export to Text, Export to PS, and Export to XML. By default, the buttons are
invisible on the toolbar area. You have to add them to the toolbar area by modifying the index.jsp file
in <install_root>\public_html\dhtmljsp.
Use the following two API functions to control the buttons:
public void customizeToolbar(String SessionId, String RptSetId, String toolbarname, int[] buttonId);
●
●
public void customizeToolbar(String SessionId, String RptSetId, String toolbarname, int[] buttonId,
boolean isVisible);
Explanation of these parameters:
●
SessionId - session ID, which can be retrieved by DHTMLUtil.getSessionID(request).
●
RptSetId - report ID, which can be retrieved by obDHTMLUtil.getRptSetId(request).
●
toolbarname - toolbar name, such as "Standard", "Analysis", "View", or user-defined ones.
●
buttonId[] - toolbar button ID. It is an integer array, so you need define an integer array variant.
For example: int[] mybuttonid ={DHTMLConstant.TOOLBAR_EXPORTTOPDF, DHTMLConstant.
TOOLBAR_EXPORTTOXLS, TMLConstant.BTN_EXPORT_TO_RTF}
The array elements available for one-step exporting are:
●
❍
DHTMLConstant.TOOLBAR_EXPORTTOPDF
❍
DHTMLConstant.TOOLBAR_EXPORTTOXLS
❍
DHTMLConstant.TOOLBAR_EXPORTTORTF
❍
DHTMLConstant.TOOLBAR_EXPORTTOHTML
❍
DHTMLConstant.TOOLBAR_EXPORTTOTEXT
❍
DHTMLConstant.TOOLBAR_EXPORTTOPS
❍
DHTMLConstant.TOOLBAR_EXPORTTOXML
isVisible - whether or not to show the buttons defined with buttonID[]. true -- show, false -- hide.
This parameter can be absent, and then the value is true.
For example, if you want to add the Export to HTML button to the Export toolbar, then:
1. Open the file index.jsp.
2. Add the code
int[] temparray = {DHTMLConstant.TOOLBAR_EXPORTTOHTML};
dhtmlConfig.customizeToolbar(SessionID, RptSetId, "Standard", temparray, true);
before
//<!-- Tool Bar -->
if(dhtmlConfig.isFeatureEnabled(SessionID, RptSetId, DHTMLConstant.
FEATURE_TOOLBAR)){
3. Start JReport Server.
4. Run a report in Page Report Studio, and you will see a new button Export to HTML is displayed on
the Export toolbar.
To add more than one button to the toolbar area, for example, adding Export to HTML and Export to
PDF buttons to the Export toolbar:
1. Open the file index.jsp.
2. Add the code
int[] temparray = {DHTMLConstant.TOOLBAR_EXPORTTOHTML, DHTMLConstant.
TOOLBAR_EXPORTTOPDF};
dhtmlConfig.customizeToolbar(SessionID, RptSetId, "Standard", temparray, true);
before
//<!-- Tool Bar -->
if(dhtmlConfig.isFeatureEnabled(SessionID, RptSetId, DHTMLConstant.
FEATURE_TOOLBAR)){
3. Start JReport Server.
4. Run a report in Page Report Studio, and you will see the buttons Export to HTML and Export to
PDF are displayed on the Export toolbar.
5. Click the added button on the toolbar of the report page, the report will be exported to the
corresponding format, using the default values of the format options.
Controlling user access to different export formats
JReport introduces an access control ability which can restrict different users to export report result to
different formats.
How to realize the access control ability
You can restrict the report result formats for users by passing values to a variable. That is the global
variable enableTypes in both customize_panel.jsp and save_result.jsp files in <install_root>
\public_html\dhtmljsp folder. The value of enableTypes should be Integer, and JReport gives you the
following integers to represent the corresponding report result types:
Report Result
Format
Int. Value
HTML
0
PDF
1
Excel
2
Text
3
RTF
4
XML
5
PostScript
6
You can specify a value or an array to enableTypes using the integers in the above table. Or you can
also use the integers which are not mentioned above, but if you do so, the Int. values will be ignored,
and do not function. That is to say, if you pass the array {1,2,5,9,-2} to enableTypes, 9 and -2 will be
ignored and {1,2,5} will work, so PDF, EXCEL, XML formats can be in use.
Example
Assume that there are two users, user1 and user2. When user1 logs on, run a report in Page Report
Studio, he can only export the report result as PDF and HTML formats. While user2 can export the
report result as RTF and XML formats when logging on. To realize it, you can use the following codes in
customize_panel.jsp or save_result.jsp file:
int[] enableTypes=null;
String UserName=null;
UserName=DHTMLUtil.getUserName(request);
if(UserName.equalsIgnoreCase("user1"))
enableTypes=new int[]{1,0};
if(UserName.equalsIgnoreCase("user2"))
enableTypes=new int[]{4,5};
Customizing warning messages
You can customize the warning messages when exporting the report result to XML through Page Report
Studio. With this function, you can specify what you want to show as a warning message. The custom
warning messages are supported across web browsers.
To customize the warning messages, you need to customize the jsp files using either of the following
two methods:
Method 1
1. Open the save_result.jsp file in the <install_root>\public_html\dhtmljsp folder with your
favorite editor.
2. Specify the value of customMsgForXML in the save_result.jsp to whatever you want. The value
cannot be "" or null.
3. Run a report in Page Report Studio, click Menu > File > Export to display the Export dialog.
4. Select XML from the Select Report Result Format drop-down list, and if necessary, modify other
properties as required, then click OK.
5. A warning message shows as you have defined.
Method 2
You can also export the report result via the Export panel instead of clicking Menu > File > Export. By
default, the panel is hidden. So, the following is another way to create custom warning messages:
1. Open the customize_panel.jsp file in the <install_root>\public_html\dhtmljsp folder with your
favorite editor.
2. Set the class of panelDIV to visibleMargin to show the Export panel on web browser.
3. Specify the value of customMsgForXML in customize_panel.jsp.
4. Run a report in Page Report Studio, and the Export panel together with the report shows.
5. Select XML from the Select Report Result Format drop-down list, and if necessary, modify other
properties as required, then click OK.
6. A warning message shows as you have defined.
For example, using method2, when you need to export the report result as XML, and if you want to
show "This is IE Browser" while browser is IE, you need to set panelDIV in customize_panel.jsp file to
visibleMargin as follows:
<div id="<%=DHTMLConstant.DHTML_PREFIX%>panelDIV" class="visibleMargin">
And then customize CustomMsgForXML in the same jsp file as follows:
String browserName=request.getHeader("User-Agent");
String customMsgForXML ="This is "+browserName;
Access JReport Server via IE, run a report in Page Report Studio, select XML from the Select Report
Result Format drop-down list in the Export panel, and click OK. Then a pop-up box will show you "This
is IE Browser".
Analytic reporting
Page Report Studio provides you with a convenient and powerful tool to analyze your business
information. By providing secure web access to business data and making the data interactive, Page
Report Studiofacilitates data analysis.
Page Report Studio enhances the utility of production reports by making them interactive - allowing
you to define your view of data to make it more useful. Through a user-friendly web GUI, report
contents can be easily navigated, drilled, and viewed in detail.
Page Report Studio uses the Resource View panel to provide a business-oriented view of databases.
This view shields end users from having to understand database connectivity and SQL syntax while
allowing IT professionals to maintain control of business data and to ensure its integrity. Using the
Resource View panel, Page Report Studio dynamically builds SQL statements to retrieve data and
automatically generate multidimensional data cubes. These cubes contain the underlying data structure
which makes data analysis possible.
The following topics describe the analytic reporting features:
●
An introduction to business/report cubes
●
Applying filters
●
Using cube elements
●
Using dynamic resources
●
Drilling through the report data
●
Manipulating data components
●
Adding conditional formats to fields
●
Converting between components
●
Sorting report data
●
Searching for text in a report
Note: A component created in JReport Designer is based on a dataset, while that created in Page
Report Studio is based on a business/report cube. For the former, if you want to do analytic actions in
Page Report Studio, such as adding a cube element, converting the component type, drilling it, or
changing chart definition, Page Report Studio will need to convert its fields to cube elements (for
details, see Converting query-based components to report cube-based in the JReport Designer User's
Guide). When conversion conditions are fulfilled, when you perform analytic actions in Page Report
Studio, you will be prompted with the Convert Data Fields dialog to confirm the conversion. However, if
the report tab level property Automatic Cube Initialization has been set to true when the report is
designed in JReport Designer, the data fields will be automatically converted to cube elements when
the report is opened in Page Report Studio.
An introduction to business/report cubes
A business/report cube, which is needed for creating multidimensional data cubes, contains database
connections and relationships between cube elements. The business/report cube shields report end
users from having to understand the physical structure of a data source, and enables them to build
reports and analyze data based on a set of cube elements they can understand. It also enables IT
professionals to maintain control of the business data and ensure its integrity, while presenting end
users with an intuitive view of the underlying data structures.
To make use of a business/report cube, you need to first define it at report design time in JReport
Designer. For additional information, see Business/Report Cubes in the JReport Designer User's Guide.
A business/report cube may contain category objects and cube elements (dimension objects, measure
objects, and detail information objects). You can insert these cube elements or remove them to change
the report result when you view reports in Page Report Studio.
●
●
Category objects
Category objects contain a collection of cube elements. A business/report cube may contain more
indicates that an object is a category.
than one category. In the Resource View panel, the icon
Categories are only for categorizing cube elements, and they cannot be inserted into a report. The
category is often used for indicating the name of the underlying DBMS table.
Dimension objects
Dimension objects are cube elements that will become the basis for analysis in a report. They
characteristically return text or date values. In the Resource View panel, the icon
indicates that
an object is a dimension object. A dimension object can be inserted wherever a group field can be
inserted into. It can be inserted as a column or row field in a crosstab, or as a group field or detail
field in a banded object or a table, or displayed as category/series field in a chart.
●
Measure objects
Measure objects are numeric cube elements that are calculated dynamically at runtime. The icon
indicates that an object is a measure object. A measure object can be inserted wherever a summary
can be inserted. For instance, it can be inserted into the group header or footer panel in a table or
banded object, or into a crosstab as an aggregate field. A measure object can also be used as a
detail field in a banded object or table although it will display the same aggregate value for every
detail line. Page Report Studio will calculate the summary values based on the group level the
measure object has been inserted into.
●
Detail Information objects
Detail Information objects provide additional information. The icon
indicates that an object is a
detail information object. It can be inserted wherever a DBField can be inserted. For example, you
can insert a detail information object into a table or banded object as a detail field.
Applying filters
You can apply filters to business/report cubes and data components such as banded objects, tables, crosstabs and
charts of a page report so as to narrow down the data displayed in the page report.
Applying filters to business/report cubes
When creating reports in Page Report Studio, you can choose to apply some filter to the specified business/report
cube to narrow down the data scope of the business/report cube. Filters for business/report cubes are defined into
two categories in Page Report Studio: predefined filters and user defined filters. As the name suggests, predefined
filters are defined on business/report cubes in advance in JReport Designer, and user defined filters are created on
business/report cubes while they are used in Page Report Studio.
Filters can be applied to business/report cubes in Page Report Studio in the following ways:
Applying a filter to a business/report cube while creating a report
1. In a Page Report Studio window, click Menu > File > New Page Report to display the New Page Report
dialog.
2. Specify the title of the report as required in the Report Title text box.
3. In the Choose Report Layout box, select the layout as Banded, Crosstab, Table or Chart and then click OK.
4. In the corresponding report wizard, select the required business/report cube for the report, and the fields you
want to display in the report.
5. Click the Query Filter screen.
All the predefined filters of the selected business/report cube are listed in the Query Filter drop-down list.
Choose the one you want to apply. If you want to further edit the filter, click the Edit button and then redefine
the filter as required. The edited filter will then be saved as a user defined filter to the business/report cube.
If you prefer to define a filter on your own, select User Defined from the Query Filter drop-down list, then
define the filter according to your requirements.
There are the basic and advanced modes of the screen for you to define either simple or complex filter
expressions.
❍
To define a filter using simple expressions:
a. Make sure the dialog is in the basic mode.
b. From the field drop-down list, select the field on which the filter will be based.
c. From the operator drop-down list, set the operator with which to compose the filter expression.
d. Type the values of how to filter the field in the value text box, or select one or more values from the
drop-down list.
e. If you want to add another condition line, from the logic operator drop-down list,
■
■
To add a condition line of the AND relationship with the current line, select AND, then define the
expression as required.
To add a condition line of the OR relationship with the current line, select OR, then define the
expression as required.
Repeat this to add more filter expressions if required. To delete a condition line, click
on its left.
❍
To define a filter using complex expressions:
a. Switch the dialog to the advanced mode.
b. Click the Add Condition button to add a condition line.
c. From the field drop-down list, select the field on which the filter will be based.
d. From the operator drop-down list, set the operator with which to compose the filter expression.
e. Type the values of how to filter the field in the value text box, or select one or more values from the
drop-down list.
f. To add another condition line, click the Add Condition button and define the expression as required.
Then, click the logic button until you get the required logic to specify the relationship between the two
filter expressions. The logic can be AND, OR, AND NOT, or OR NOT.
g. Repeat the above steps to add more filter expressions if necessary.
To group some conditions, select them and click the Group button, then the selected conditions will be
added in one group and work as one line of filter expression. Conditions and groups together can be
further grouped. To take any condition or group in a group out, select it and click Ungroup. It is the
equivalent of adding parenthesis in a logic expression.
To adjust the priority of a condition line or a group, select it and click the Up or Down button.
To delete a condition line or a group, select it and click the Delete button.
6. Click Finish in the report wizard and the specified filter will be applied to the business/report cube, so that
your report will get data that meets the filter condition only.
Applying a filter to a business/report cube while inserting a data component
1. In a Page Report Studio window, do either of the following:
❍
❍
Click Menu > Insert > Banded Object/Table/Crosstab/Chart, point to the destination, and then click
the mouse button.
Drag Banded Object, Table, Crosstab, or Chart from the Toolbox panel to the destination.
2. In the corresponding report wizard, select the required business/report cube for the component, and the fields
you want to display in the component.
3. In the Query Filter screen, specify the filter you want to apply to the business/report cube from the Query
Filter drop-down list, or define a filter according to your requirement.
4. Click Finish to create the component and the specified filter will be applied to the business/report cube.
Applying a filter to a business/report cube after a report is built
1. Select the component in a report which was created on a business/report cube by clicking anywhere in it, and
at the upper left corner of the component.
then clicking the icon
2. Click Menu > Report > Query Filter, or right-click the component and select Query Filter from the shortcut
menu to display the Query Filter dialog.
3. From the Query Filter drop-down list, select the filter you want to apply to the business/report cube used by
the component, or define a filter according to your requirement.
4. Click OK to apply the filter to the business/report cube.
Notes:
●
A JReport Live license for JReport Server is required in order to use this feature. If you do not have a Live license
please contact your Jinfonet Software account manager to obtain a license.
●
●
Business/report cube filters are defined on the component level in Page Report Studio, which means each time
you create a component, you can apply a filter to the business/report cube it applies to and it will not affect other
components based on the same business/report cube.
In Page Report Studio, you cannot edit the predefined filters that have been created on a business/report cube
at the Designer side. You can just edit the condition based on a predefined filter and then the edited filter will be
saved as a user defined filter.
Filtering the data components in a report
There are the following ways you can take in order to filter the data components in a page report: using the Filter
dialog, using filter controls, using the shortcut menu, and using labels.
Using the Filter dialog
To set the filtering conditions using the Filter dialog:
1. Click Menu > Report > Filter, or the Filter button
on the Analysis toolbar to show the Filter dialog.
2. Select the component on which the filtering will be based from the Apply to drop-down list.
3. Define the filter as required. There are the basic and advanced modes of the dialog for you to define either
simple or complex filter expressions.
4. Click OK to make the filter take effect and return to the report.
Using filter controls
A filter control is a web control used to filter one or more data components, which refer to tables, banded objects,
charts, and crosstabs, in a report using the same data source. A filter control can do filtering based on one field.
For details, see Using filter control to filter report data.
Using the shortcut menu
You can also use filter-related commands on the shortcut menu to filter the data in a banded object or table. To do
this, point to any value of the field other than the group by field, by which you want to filter data, then right-click
to show the shortcut menu. You will see the Filter item which provides a submenu containing the following
commands:
●
●
Remove Filter
This command is enabled after you have applied filtering on the field to the banded object or table. Clicking this
item will remove all filters on this field.
Top N
Shows the Top N dialog with which you can filter data to display records that meet the Top N condition.
For example, if you input 3 in the Top N dialog for a certain field, then only the records with the field value equal
to one of the first three field values will be displayed.
●
Bottom N
Shows the Bottom N dialog with which you can filter data to display records that meet the Bottom N condition.
For example, if you input 3 in the Bottom N dialog for a certain field, then only the records with the field value
equal to one of the last three field values will be displayed.
●
●
Field values
"Field values" is not the name for a command on the Filter submenu, but represents some items which are the
values of the field you have right-clicked. Selecting any field value listed here will make the banded object or
table only display records with the field value equal to the selected one.
More
This command is enabled if the Filter submenu cannot list all field values. When it is enabled, clicking it will show
the Select Values dialog. You can select one value in this dialog and apply the setting, after which the banded
object or table will only display records with the field value equal to that value.
Using labels
You can also use a label to control the filter condition in a banded object or table. This feature needs to be enabled
at report design time.
1. In JReport Designer, select a label in a banded object/table, and then set its Filterable property to true.
2. Set the field by which you want to filter records as the value of the label's Bind Column property.
3. Save the report and publish it to JReport Server.
4. Run the report in Page Report Studio, and you can find that a button
is beside the label. Click it to show
the Filter list, which contains All, Top N, Bottom N, Custom Filter, the field values, and More (if there are too
many distinct values for the field), then click the corresponding item to filter the records.
After applying a filter on the field decided by the Bind Column property, the button
will be affixed with a
check mark, and you can still click it to show the Filter list, in which the All item can help you remove the
filters on the field.
Notes:
●
●
●
●
You can also filter records by using the shortcut menu for a label in the same way as for a field value, provided
you have set its Bind Column property value to a field.
When using the shortcut menu for a field value or label to filter, all the items (Remove Filter, Top N, Bottom N,
and More) will be showed by default. If you want to disable some of the items, you should set the field's Filter
Options property when designing the report in JReport Designer. For details, see Setting filter options for a field
in the JReport Designer User's Guide.
For filtering the data using shortcut menu or labels, you may notice that the corresponding filter expressions will
appear in the Filter dialog if you open this dialog.
JReport allows you to define the display names for fields to be shown in the Filter dialog. For detailed
information, see Customizing the field display names in the JReport Designer User's Guide.
Using cube elements
After a report has been built and published to JReport Server, you can open it in Page Report Studio and use the Resource View
panel to analyze data of the report by dragging cube elements from the panel to the component (banded object, table or crosstab)
in the report, provided that the data objects used by the component can be converted to corresponding cube elements (see the note
in Analytic reporting for details).
on the View
Tip: To display the Resource View panel, click Menu > View > Resource View or the Resource View button
toolbar. You can use the search bar at the top of the panel to search for any desired resource in a fast and convenient way.
The following examples show how to analyze reports using cube elements. These examples are based on the WorldWideSalesRC
report cube in Data Source 1 of the SampleReports catalog. The report cube contains thirteen dimension objects (City, Country,
Customer Name, Region, State, Territory, Sales Month, Sales Quarter, Sales Year, Category, Product ID, Product Name, and Product
Type), eleven detail information objects (Address 1, Country, Customer Name, CustomerCityStateZip, Phone, Cost, Discount, Order
Date, Quantity, Total, and Unite Price), and three measure objects (Total Cost, Total Quantity, and Total Sales). Total calculates the
value of the formula ("Unit Price" * Quantity - "Unit Price" * Quantity * Discount/100), Total Sales defines an aggregate function
Sum on the formula Total, Total Cost is Sum on Cost, and Total Quantity is Sum on Quantity.
●
Example 1: Analyzing a banded report
●
Example 2: Analyzing a crosstab report
●
Example 3: Analyzing a table report
Example 1: Analyzing a banded report
1. In Page Report Studio, design a banded report titled Sales in China on WorldWideSalesRC, which shows the fields Product ID,
Country, Product Name, Unit Price, Quantity, and Discount, and applies the ClassicBlue style.
First, we will apply a filter to the banded object to narrow down data scope.
2. Click the Filter button
on the Analysis toolbar. In the Filter dialog, define the filter as COUNTRY = 'China'.
We want to further sort the banded object by Product Name ascending.
3. Right-click any of the Product Name values and select Sort > Ascend from the shortcut menu.
4. As the banded header panel holds no data, we can hide it by right-clicking it and selecting Hide from the shortcut menu.
Now the report shows as follows:
Next, we will add the Total field to the banded object and group by the City field.
5. Click the Resource View button
shown in the panel.
on the View toolbar, then resources of the report cube the banded object uses will be
6. From the Resource View panel, drag the detail information object Total in the Orders Detail category to the detail panel of the
banded object.
7. Drag the dimension object City in the Customers category to the banded page header panel, when a blue line appears, release
the mouse button.
8. Finally, drag the measure object Total Sales in the Orders Detail category to the group footer panel.
9. We can now analyze the data in various ways. For example, if we want to see the sales by category instead of city, right-click
on any of the City fields and select Drill To > Category from the shortcut menu, then we can see the same report with an
entirely different view of the data.
Example 2: Analyzing a crosstab report
1. Design a crosstab report on WorldWideSalesRC showing product sales information with Product Type (Ascend) as the column
field, Category (Ascend) as the row field, and Total Cost as the aggregate field. Apply the ClassicBlue style to the crosstab.
First, we want to replace the product type information with region information, and display the total sales of each product category
in each region.
2. Remove Product Type from the crosstab by pointing to the header Product Type (Decaf or Regular), then dragging it outside
the report page. A message box will prompt you whether or not to remove the field. Click OK to confirm, and we can see that
the crosstab no longer contains the Product Type information.
3. Click the Resource View button
in the panel.
on the View toolbar, then resources of the report cube the crosstab uses will be shown
4. Drag the dimension object Region in the Customers category from the Resource View panel to the crosstab until a blue line
appears indicating the group level of the dimension.
5. Drag the measure object Total Sales in the Orders Detail category to the aggregate area of the crosstab.
Now the total sales of each product category in each region is displayed.
6. Then we would like to see the territory information for the EMEA region. Click in the EMEA header and we will drill down to the
next lower level based on the hierarchy defined in the report cube which in this case is Territory.
Using the same way, we can further drill down to the country, then the city levels which have been defined in the hierarchy to
get detailed sales information in each city. For more details about drilling, refer to Automatic drilling.
Example 3: Analyzing a table report
For a table, you can analyze its data in the same way as for a banded object. Furthermore, Page Report Studio provides some
analysis methods specific for tables.
1. Design a table report on WorldWideSalesRC, which shows the fields Product Type, Country, Product Name, Unit Price, Quantity
and Discount, and applies the ClassicBlue style.
2. Add a filter COUNTRY = 'China' AND PRODUCT TYPE = 'Decaf' to the table (see Example 1 for details on filtering). The table
displays as follows:
For a table, we can insert a column (or row for horizontal table) at a specific position. So next, we will insert the dimension object
City into the table.
3. Click the Resource View button
the panel.
on the View toolbar, then resources of the report cube the table uses will be shown in
4. Drag City in the Customers category from the Resource View panel to the boundary between the first column (Product Type)
and the second column (Country) in the table until a blue line appears.
The report result will be regenerated.
Tip: When you add a column to a table, if the width of the table exceeds the defined page size, you will be prompted
whether to allow JReport to adjust the page size automatically so as to place the column. Click Yes in the message box to
have the page size adjusted, or No to make the columns in the table compressed. Also, If you do not want to display the
message in future, check Don't prompt the message again in the message box, or uncheck Always Prompt Whether
to Adjust Page Size Automatically in the Profile > Customize Profile > Page Report Studio > Properties > Default tab.
If you choose not to show the message box again, when the table width exceeds the defined page size, JReport will
always adjust the page size automatically.
Next, we want to show the total information and remove the product name information. This can be done with a single drag-anddrop.
5. Drag the detail information object Total in the Orders Detail category to the header Product Name until the label Product Name
is highlighted in a blue background.
Now, the total value for each record will be generated.
As a table column can contain more than one field, next, we will add the measure object Total Sales to the Total column.
6. Drag Total Sales from the Resource View panel to any value in the Total column.
The report result will be regenerated.
Here 182,298.76 is the sum of all total values. In this way, the title for the added field will not be automatically created.
At last, we want to change the order of the Total and Discount columns in the table.
7. Drag the label Total to the right of the Discount column, when a blue line appears along the right boundary of the Discount
column, release the mouse button.
We can see that order of the columns changes.
Notes:
●
●
●
A JReport Live license for JReport Server is required in order to use this feature. If you do not have a Live license please contact
your Jinfonet Software account manager to obtain a license.
When you are using a report cube, the records will be fetched based on the query which contains the report cube in JReport
Designer; while for a business cube, there is no predefined query and you will fetch records from the data source using dynamic
SQL.
To use the Resource View panel so as to add cube elements to the report, you should make sure that this ad hoc feature is
enabled in the specified Page Report Studio feature profile. This setting can only be made by administrators.
Using dynamic resources
When you drag cube elements from the Resource View panel to analyze data of a report, sometimes you may find that the cube elements that have
been predefined in the business/report cube cannot meet your requirements, in which case, you can create some dynamic resources and use them
in the report to get the desired data. Then when you save the report, the dynamic resources will be saved along with the report as its resources.
Dynamic resources are report tab level resources, which means they are only available to the report tab for which they are created.
Dynamic resources in Page Report Studio include formulas and measures.
Creating and using dynamic formulas
You should have some knowledge of the formula syntax before you can successfully compose a formula with no errors. To learn the formula syntax,
refer to Formula syntax.
To create a dynamic formula:
1. In the Resource View panel, expand the Dynamic Resources > Formulas node, then click <Add Formula•gt; to display the Formula Editor
window.
2. Enter a name for the formula in Formula Name text field.
3. Compose the formula by selecting the required fields, functions and operators from the Fields, Functions and Operators boxes. You can also
write the formula by yourself in the editing box.
For details about the functions and operators, refer to Built-in functions and Operators.
4. Click the Check button
to check whether or not the syntax of your formula is correct.
5. When done, click the OK button to create the formula.
Once a dynamic formula has been created, you can then drag it from the Resource View panel to the desired position in the report as a detail
information object for data analyzing. The formulas can also be used to control object properties if you are an advanced user and provided that the
Use Dynamic Formula in Property is checked on the Report menu.
Also, if you want to further edit an existing formula or remove any formula that is not required, right-click the formula and then click the
corresponding command on the shortcut menu. However, if the formula has been used in the report or referenced by another formula, it cannot be
deleted.
Creating and using dynamic measure objects
In Page Report Studio, you can also create dynamic measure objects by mapping them to the available resources which include dimension objects,
detail information objects in the current business/report cube and the dynamic formulas that have been created in the report.
To create a dynamic measure object:
1. In the Resource View panel, expand the Dynamic Resources > Measures node, then click <Add Measure•gt;. The Add Measure dialog is
then displayed.
2. In the Measure Name text field, specify the display name of the measure.
3. Click the button
next to the Mapping Name text field to specify a field or a formula on which the measure object is based.
4. From the Aggregate Function drop-down list, specify the aggregate function for the measure object.
5. When done, click OK to create the measure object.
You can also create a dynamic measure object on a dynamic formula. To do this:
1. In the Resource View panel, right-click the formula in the Dynamic Resources > Formulas node, then select Create Measure from the shortcut
menu.
2. In the Add Measure dialog, specify the display name of the measure object and the aggregate function as required.
3. When done, click OK.
Once a dynamic measure object has been created, you can then drag it from the Resource View panel to the desired position in the report so as the
get the desired data. And if you want to edit any dynamic measure object or delete it, right-click the measure object and click Edit or Delete on the
shortcut menu (a measure object that has been used in report cannot be deleted).
Notes:
●
A JReport Live license for JReport Server is required in order to use this feature. If you do not have a Live license please contact your Jinfonet
Software account manager to obtain a license.
●
You can only use JDK (not JRE) to compile formulas created in JReport and save a dynamic formula with no errors into a report.
●
Currently, global variables are not supported in dynamic formulas.
●
When formulas reference display names or mapping names, the names should not contain any of below characters if the names are not quoted by
double-quotation marks "":
"~", "`", "!", "@", "#", "$", "%", "^", "&", "*", "(", ")", "-", "+", "=", "{", "}", "[", "]", "|", "\\", ":", ";", "\", " ' ", "<", ",", ">", ".", "?", "/"
Examples:
●
❍
Expression @Customer#; will cause a syntax error. But @"Customer#" is ok.
❍
If a field has the display name Category.Measure, when adding it to a formula, quote it as "Category.Measure" or "Category"."Measure".
Now in JReport, the display names of objects in a category in a business/report cube cannot be duplicated. When you choose to create a dynamic
formula/measure object on an object which was created in a previous version and it has the same display name as another object, you will be
prompted with a message asking you to give a new name for the object in JReport Designer first.
Drilling through the report data
In a page report runing in Page Report Studio, you can choose to show certain groups of records
according to your requirements, and switch among the groups to see the data you want.
This section presents two kinds of drilling in Page Report Studio. They are:
●
Automatic drilling
●
Going
Automatic drilling
Automatic drilling enables you to switch from the current dimension to another dimension by using
system-defined commands on the shortcut menu, and it is divided into four kinds:
●
●
●
●
Drill-to
It enables you to obtain a different view of data by switching among dimensions.
Drill-to-by-value
It enables you to filter data based on a drill-to action so as to obtain a more detailed view of the data.
Drill-down
It enables you to drill data to lower dimensions according to predefined hierarchies.
Drill-up
It enables you to drill data to higher dimensions according to predefined hierarchies.
Drilling actions are performed on crosstabs, charts, grouped tables and banded objects, whose data are
based on business/report cube or if on query, data fields of which can be converted to corresponding
cube elements (see the note in Analytic reporting for details). After drilling, the new component can be
analyzed in the same way as the original one.
Assume you have created a crosstab report on the report cube WorldWideSalesRC in Data Source 1 of
the SampleReports catalog showing product sales information with Region as the column field, Sales
Year as the row field, and Total Sales as the summary field, and applied the default style to the
crosstab. The crosstab shows as follows:
We will now take the crosstab as an instance to illustrate the automatic drilling functions.
Drill-to
1. Right-click any value of Region, APAC for example, and choose Drill To from the shortcut menu.
The list of dimensions available for Drill To will appear on the submenu.
2. Click Product Type on the submenu, then in the regenerated result, we can see that Sales Year
remains the dimension for rows and Product Type becomes the dimension for columns.
3. Repeat Steps 1 and 2 to drill the data to other dimensions. Row field can also be drilled freely.
4. To go back to the original report, right-click any value of Product Type, choose Drill To > Region
from the shortcut menu.
Drill-to-by-value
1. Go back to the original report in the above example.
2. Right-click the value APAC of the Region dimension, and point to Drill to By Value on the
shortcut menu. A submenu for the command is displayed, which lists the same items as those of
Drill To.
3. Click Product Type too and the result will be regenerated.
We can see that the result is different from that of drill-to. This is because that, for the drill-to-byvalue action, the dimension of columns changes to Product Type by the Region value APAC. That
is, on the basis of the drill-to action, a filtering action where Region = APAC is further performed,
and thus the result of drill-to-by-value is generated.
In addition, when a drill-to-by-value action is performed, the Drill Filter panel will be displayed on
the left of the Page Report Studio window, which shows the dimension and the value the filter is
based on.
4. To go back to the original report, first delete the drill filter in the Drill Filter panel by clicking X
next to the dimension name, then right-click any value of Product Type and click Drill To >
Region from the shortcut menu.
Drill-down
Drill-down actions are based on predefined business/report cube hierarchies. The report cube
WorldWideSalesRC contains a hierarchy Geography, which allows you to drill a dimension
(corresponding to a high level) down to the one-level-lower dimension.
1. Go back to the original report in the above example, right-click the value APAC, on the shortcut
menu, point to Drill Down, and we can see that Territory is listed as the submenu item.
2. Click Territory to see the result. It displays the data about territories in the Asia Pacific region.
3. The one-level-lower dimension for Territory defined in the hierarchy is Country. Now click Asia
directly and JReport will also drill it down to Country.
After these two drill-down actions, we can see two filters are added in the Drill Filter panel, Region
= APAC and Territory = Asia.
This is because, when you perform a drill-down action, a filter will be created based on the value
you click on. In this example, we first click on the APAC region, so JReport drills this region onelevel down to display territories in APAC, and thus the filter Region = APAC is created. If you want
all data in the one-level-lower dimension to be displayed when you drill down a dimension, you
can remove the corresponding filter from the Drill Filter panel.
Drill-up
Drill-up actions allow you to drill a dimension (corresponding to a low level) up to the one-level-higher
dimension.
1. Based on the report result after drill-down, right-click any value of Country, China for example, on
the shortcut menu, point to Drill Up, and we can see that Territory is listed as the submenu item.
2. Click Territory to see the result. The dimension is drilled one level up. Territory is now the
dimension for columns.
3. The one-level-higher dimension for Territory defined in the hierarchy is Region. Now right-click
any value of Territory, Asia for example, on the shortcut menu, point to Drill Up and click
Region, JReport will drill it up to Region.
Notes:
●
●
●
●
●
A JReport Live license for JReport Server is required in order to use this feature. If you do not have a
Live license please contact your Jinfonet Software account manager to obtain a license.
For banded object and table, you can right-click its group header/footer to show the shortcut menu
so as to use the automatic drilling functions, you can also right-click field values in the group header/
footer to achieve this.
For dimension objects that not used as group fields in a banded object or table, automatic drilling
doesn't take effect.
JReport allows you to define display names for items to be shown on the drill-related menu items.
For detailed information, see Customizing the field display names in the JReport Designer User's
Guide.
When performing the drill-down action on dimension objects of reports created in JReport Designer,
if there are other actions defined on the dimension objects at the same time, you can drill down the
objects by a single click only when the click priority of the drill-down action is specified to be the
highest at report design time. Otherwise, you have to use the Drill Down command on the objects'
shortcut menu to perform the action.
Going
In a page report running in Page Report Studio, you can select to show certain groups of records in a banded object according to your
requirements. You can also switch among the groups to see the data you want. This action is called going, which divides into go-to, goup, go-down, and go-to-detail, as indicated in the diagram.
●
●
●
●
Go-to
The go-to action allows you to switch the data presented in a banded object from any group to any other group.
Go-up
Go-up means to jump up one group level to show the records of a particular group.
Go-down
Go-down means to jump down one group level to show the records of a particular group.
Go-to-detail
Go-to-detail allows you to concentrate on the details of a group.
Going actions are available only for banded objects that contain groups, and fields in which have not been converted to cube elements
of a report cube. Going actions do not apply to banded objects created in Page Report Studio. After a going action has been performed,
the data presented in the banded object will be re-loaded from the data buffer, showing only the records in the selected group, and the
new report created by going can also be viewed, printed, and exported to other format in the same way as the original report. In
addition, a "going path", which tracks the going action, will be displayed in the Go To drop-down list on the navigation bar, with which
you can easily return to the original report.
The following describes the use of the going actions based on Banded_Link.cls in the SampleReports folder of Public Reports, which
contains a banded report.
Go-to
1. Run Banded_Link.cls.
2. Point to the region APAC, right-click and select Go To > APAC > Vietnam from the shortcut menu.
Then only the data about Vietnam is displayed.
3. To return to the original status, right-click any value and then click Go To > ROOT on the shortcut menu; or from the Go To dropdown list on the navigation bar, select Product Sales by Country.
You may notice that the result is not dependent on what you right-clicked, in other words, you can right-click any field value in the
banded object or even the blank part of a group header/footer panel or detail panel, in order to perform a go-to action.
Go-up
For a go-up action, you need to right-click a group header/footer panel or any object in the panel, at the same time, you should make
sure that this group level is lower than some other group levels.
1. Undo the go-to action in the above example.
2. Point to any country, for example China, right-click and select Go Up > LATAM from the shortcut menu.
Then only the data about LATAM is displayed.
At Step 2, you may find that items listed on the Go Up submenu are regions of the Region group level which is one level higher than the
current group level - Country. That is, the go-up action allows you to focus your attention on the groups of a higher level than what you
right-click.
Go-down
For a go-down action, you need to right-click a group header/footer panel or any object in the panel, at the same time, you should
make sure that this group level is higher than some other group levels.
1. Undo the go-up action in the above example.
2. Point to APAC, right-click and select Go Down > Singapore from the shortcut menu.
Then data about Singapore is displayed.
At Step 2, you may find that items listed on the Go Down submenu are countries of the Region group level which is one level higher
than the group level of Country, and only countries in the Asia Pacific (APAC) region are displayed. That is, the go-down action allows
you to focus your attention on the groups of a lower level than what you right-click, and only those lower-level groups which are related
with the higher-level group value you right-click will be concerned.
Go-to-detail
If a banded object contains group information, then a field, label, image or shape map in a group header/footer panel of the banded
object can be used to obtain information of that group, and a chart in a banded object also has the similar function. The go-to-detail
action should be predefined at report design time. You can refer to Obtaining detailed information from a banded object in the JReport
Designer User's Guide for more information.
1. Undo the go-down action in the above example.
2. Point to LATAM, right-click and select Go to Detail from the shortcut menu. Then only the data about this region is displayed. You
can also click LATAM directly to perform the go-to-detail action, provided that the click priority of the action is specified to be the
highest at report design time.
Manipulating data components
You can manipulate data components, which refer to crosstabs, tables, banded objects, charts and
geographic maps, in Page Report Studio as shown below. However, most of the manipulations require
selecting the component first. To select a component, click anywhere in the component, when the icon
appears at its upper left corner, click the icon.
Note: When manipulating data components, a JReport Live license for JReport Server is required in
order to use the features involving report cube/business cube or changes of report template. If you do
not have a Live license please contact your Jinfonet Software account manager to obtain a license.
Setting the number of records retrieved by data components
You can set the number of records that can be retrieved by all data components in a report. To do this,
select a value to your liking (All or first 50 to name a few) from the Max Records combo box
on the Analysis toolbar. You can also directly input a positive integer here and
press Enter to retrieve the corresponding records. Alternatively, you can click Menu > Report > Max
Records to show the Max Records dialog, and then achieve the same goal. If you are making a lot of
changes to the report, it may be faster to limit the number of records to 1 page while you make the
changes then change it back to All to view the final result.
Manipulating a crosstab
●
●
Changing the dimension index in a crosstab
The dimension index in a crosstab can be modified, namely, you can move a dimension to a higher or
lower level. This operation can be performed on crosstab's containing two or more dimensions. To do
this, you can simply drag a dimension object (row/column header) to the required destination till a
blue line appears. You can also drag a column header to a row level and vice versa.
Rotating a crosstab
Columns and rows in a crosstab can be exchanged. This operation is called rotating a crosstab.
To rotate a crosstab, first select it, and then do one of the following:
●
●
❍
Click Menu > Report > Rotate Crosstab.
❍
Click the Rotate button
❍
Right-click the icon
on the Analysis toolbar.
of the crosstab and select Rotate from the shortcut menu.
Expanding/Collapsing a crosstab
For a crosstab, if it has more than one row/column group level, you can specify whether or not to
enable the crosstab to be expanded in Page Report Studio, and set the default expanding/collapsing
state of groups in outer levels. For details, see Expanding/Collapsing a crosstab in the JReport
Designer User's Guide.
Adjusting the width of crosstab fields according to the contents
When the contents in the field of a crosstab need more space to completely display, you can adjust
the width of the field according to its contents. To achieve it, first select the field, then right-click on
it and select Autofit from the shortcut menu.
Manipulating a table
●
Adjusting order of columns in a table
The order of columns in a table can be easily adjusted. To do this, drag a column header to the left
or right boundary of another column header, when a blue line appears along the column boundary,
release the mouse button, and you will see the order change.
The above description is for a vertical table. With regard to a horizontal table, you can do the same
actions on its row headers.
●
●
●
●
●
●
●
Adjusting grouping order in a table
A table may contain several group levels. The order of the group levels can also be adjusted. To do
this, drag a group field value to the required position until a blue line appears.
Hiding/Deleting table columns
A table column (for a horizontal table, the "column" corresponds to a field row) can be hidden or
removed. To do this, select the cell of the column in the table header and right-click, then select
Hide Column or Remove Column from the shortcut menu, and the column will be hidden or
removed from the table.
Showing table columns
of the
You can specify which columns will be shown in a table. To do this, right-click the icon
table, then on the shortcut menu, check the names of the columns you want to show from the Show
Column submenu.
Adjusting the width of table columns according to contents
When the contents in cells of a table column need more space to completely display, you can adjust
the width of the table column according to the contents. To do this, right-click the cell of the column
in the table header, then select Autofit from the shortcut menu.
Changing group direction
You can make the group headers that are placed horizontally in a table to be displayed vertically. To
do this, right-click the group header row and select Vertical to Detail from the shortcut menu. In
addition, if the first column of a table is group column, you can specify to place the group column
horizontally in a table. To do this, right-click the cell of the group column in the table header, and
select Horizontal to Detail from the shortcut menu.
Rotating a table
You can rotate a table to switch its appearance between the horizontal and vertical layout modes by
doing one of the following:
❍
Click Menu> Report > Rotate Table.
❍
Click the Rotate button
❍
Right-click the icon
on the Analysis toolbar.
of the table and select Rotate from the shortcut menu.
Inserting table columns
You can insert a new column in a table and it could be a common column, detail column, summary
column, or group column.
❍
To insert a common column into a table:
1. Right-click any cell in the table header, or right-click the icon
of the table.
2. On the shortcut menu, click Insert > Common Column.
❍
To insert a detail or summary column into a table:
of the table, then select
1. Right-click any cell in the table header, or right-click the icon
Insert > Detail Column/Summary Column from the shortcut menu.
2. In the corresponding insert column dialog, specify the resource you want to use for the new
column, then click OK.
❍
To insert a group column into a table:
1. Right-click any cell in the table header, or right-click the icon
Insert > Group Column from the shortcut menu.
of the table, then select
2. In the Insert Group Column dialog, select the dimension object you want to use for the new
group column from the Resources box and click
to add it as the group by field, then
specify the sorting direction of the group in the Sort column.
3. Specify the positions of the group by fields: Group Above, Group Left Above, or Group Left.
4. Repeat the above steps to add more groups if required.
5. Click OK to insert the columns.
The next time when you open the Insert Group Column dialog to add more group columns, all
the added group by fields will be listed in the dialog. You can choose to remove or edit them if
required.
Note: If you right-click any cell in the table header and use its shortcut menu to insert a
common, detail or summary column, the column will be inserted before the column in which the
cell you click on is, however, if you use the table shortcut menu to insert the column,
❍
❍
●
If it is a common column, the column will be inserted as the last column in the table.
If it is a detail/summary column, the column will be inserted after the last detail/summary
column, or as the last column in the table when there is no detail/summary column.
Converting table columns
You can convert a group column into a detail column, and vice versa.
❍
❍
To convert a group column into a detail column, select the cell of the group column in the table
header, right-click and select Convert to Detail from the shortcut menu, then the conversion is
done.
To convert a detail column into a group column:
1. Select the cell of the detail column you want to convert in the table header, right-click and
select Convert to Group from the shortcut menu.
2. In the Select Group Position dialog, specify the position for the newly converted group by field.
3. Click OK to save the changes.
●
Aggregating on a detail column
You can summarize the data in a detail column if required. To do this:
1. Select the cell of the detail column in the table header, right-click it and select Aggregate On
from the shortcut menu.
2. In the Aggregate On dialog, specify a function from the Function drop-down list to summarize
the data.
3. When done, click OK.
■
■
If the table has groups, you will find data in each group level and the whole table are
summarized respectively in the column.
If the table has no groups, the summary will be based on the whole table.
When you finish summarizing a detail column, you will find a dynamic measure object is created at
the same time which is given a default name Function_DetailFieldName in the Dynamic Resource >
Measures list in the Resources View panel and you can use it again in the current report if required.
Note: If a table is created in JReport Designer, you can add, convert columns in the table, or
aggregate on its detail columns in Page Report Studio only when data fields used by the table can be
converted to corresponding cube elements. See the note in Analytic reporting for details.
Manipulating a banded object
●
●
●
Hiding/Showing a panel in a banded object
of the banded
A panel in a banded object can be hidden or shown. To do this, right-click the icon
object, then on the shortcut menu, click the item which indicates the panel name from the Show
submenu. For a panel which is shown, the item is with a check mark, and vice versa. This operation
is also applicable for hiding/showing a row in a table.
Hiding/Showing DBFields and labels in a banded object
The DBFields and their corresponding labels in a banded object can be hidden or shown. To do this,
of the banded object, then on the shortcut menu, click the fields and labels you
right-click the icon
want to show from the Show Field submenu. For a field or label that is shown, it will be marked with
a check mark, and vise verse.
Expanding/Collapsing a group panel in a banded object
Group panels in a banded object can also be expanded or collapsed. For details, see Managing the
data of a banded object in the JReport Designer User's Guide.
Manipulating a chart
●
Modifying the definition of a chart
You can modify the definition of a chart, including the chart type, data display, and style. To do this:
of the chart or any part of the chart other than the legend and label to
1. Right-click the icon
show a shortcut menu, and then select Format Chart from the shortcut menu to display the
Chart Definition dialog.
Note: In the event that the chart is built in JReport Designer, the Format Chart command
will be available only when Page Report Studio can convert data fields used by the chart to
corresponding cube elements. See the note in Analytic reporting for details.
●
In the Chart Type tab of the Chart Definition dialog, specify the type for the chart.
●
In the Display tab, change the dimension and measure object used by the chart.
●
In the Style tab, modify the style for the chart as required. If there is only one style available, this
style will be applied to the chart by default and the Style tab will be hidden from the dialog.
Upon finishing, click OK to apply the modifications.
●
For details about how to modify the chart definition with the Chart Definition dialog, see
Creating a chart report.
In addition, if you only want to change the chart type, no matter whether the chart is originally
created in JReport Designer or Page Report Studio, you can achieve it by doing one of the
following:
❍
❍
●
Right-click the chart and on the shortcut menu, select the required type from the Chart Type
submenu, which lists all the chart types and subtypes (the current one and the inapplicable
subtypes are grayed out).
Select the chart, click the Chat Type button
suitable subtype from the drop-down menu.
on the Analysis toolbar, and then select a
Formatting chart elements
The elements (platform, paper, legend and label) in a chart can be formatted to suit your
requirement.
❍
❍
To format the platform/paper of a chart, right-click the icon
or any part of the chart except for
the legend and label and select Format Platform/Format Paper from the shortcut menu. In the
displayed format dialog, specify the settings as required. For details about the settings, refer to
Format Platform dialog and Format Paper dialog.
To format the legend/label of a chart, right-click the legend/label and select Format Legend/
Format Label from the shortcut menu. In the displayed format dialog, set the properties
according to your requirement. For details about the properties, see Format Legend dialog and
Format Label dialog.
Manipulating geographic map group markers
Going up/down on geographic map group markers
●
❍
❍
●
For the group level that is higher than some other group levels in a geographic map component,
point to its group marker, right-click it and select Go Down from the shortcut menu to jump one
group level down.
For the group level that is lower than some other group levels in a geographic map component,
point to its group marker, right-click it and select Go Up from the shortcut menu to jump one
group level up.
Showing/Hiding geographic map group markers
By default, all visible group markers are shown. To hide them, right-click the geographic map (not
the group markers) and select Hide Markers from the shortcut menu. If you want to show them
again, right-click the geographic map and select Show Markers from the shortcut menu.
Adding conditional formats to fields
You can add some conditional formats to a field, which refer to the DBField, parameter field, formula field, summary
field, and the special field Page Number or User Name, then when the specified condition is fulfilled, the defined
format will be applied to the field values for highlighting.
To add conditional formats to a field,
1. Right-click the field and select Conditional Formatting from the shortcut menu to access the Conditional
Formatting dialog.
2. Click the button
to open the Edit Conditions dialog to define the condition as required.
There are the basic and advanced modes of the dialog for you to define either simple or complex condition
expressions. See Applying filters to business/report cubes for details about how to define a condition.
3. When done, click OK to save the condition.
The newly added condition will then be displayed and highlighted in the Condition box in the Conditional
Formatting dialog.
4. In the Format box, set the format which will be applied to values of the field when the specified condition is
fulfilled, for example, the font face, font size, font color, etc.
5. Repeat the above steps to add more conditions and define the format for each condition as required.
To edit a condition, select the condition in the Condition box, then click
the condition expressions as required.
. In the Edit Conditions dialog, edit
To remove a condition and the corresponding format, select the condition in the Condition box and click
.
To adjust the priority of a condition, select the condition in the Condition box and then click
or
6. Click OK to apply the conditional formats to the field.
See also Conditional Formatting dialog and Edit Conditions dialog for details about options in the dialogs.
.
Converting between components
Converting between components enables you to view and analyze data from different aspects with
different focuses. In Page Report Studio, you can convert a crosstab into a chart and vice versa,
however, if a crosstab/chart is designed in JReport Designer, to enable the conversion, you need to
make sure that data objects used by the crosstab/chart can be converted to corresponding cube
elements (see the note in Analytic reporting for details).
Note: A JReport Live license for JReport Server is required in order to use this feature. If you do not
have a Live license please contact your Jinfonet Software account manager to obtain a license.
Converting a crosstab into a chart
To convert a crosstab into a chart:
1. Click anywhere in the crosstab, when the icon
select the crosstab, then do any of following:
appears at its upper left corner, click the icon to
and select To Chart from the shortcut menu.
❍
Right-click the icon
❍
Click Menu > Report > To Chart.
2. The Convert Data Fields dialog may appear for your confirmation on converting data fields of the
crosstab to cube elements of a business/report cube. Click OK to confirm, and the To Chart dialog
will be displayed.
3. In the Chart Type tab, specify a suitable type for the chart. With a certain type specified, you can
further define the chart as a combo chart by clicking <Add Combo Type> in the Chart Type
Groups box.
4. In the Display tab, the Resources box lists all the cube elements used in the selected crosstab
including dimension and measure objects. The chart can only be defined based on the cube
elements listed. Add a dimension object
to the Series box, and measure objects
from the Resources box to the Category box, and so
to the Show Values box respectively.
5. In the Style tab, set the style for the chart as required.
If the crosstab is in a banded object, by default, the chart converted from the crosstab will take on
the style of the banded object. If you want to apply another style to the chart, uncheck the
Inherit Style option and choose the desired style in the Style box. However, when there is only
one style available, this style will be applied to the chart by default and the Style tab will be
hidden from the dialog.
6. Click the OK button to finish the conversion.
Converting a chart into a crosstab
To convert a chart into a crosstab:
1. Click anywhere in the chart, when the icon
appears at its upper left corner, click the icon to
select the chart, then do any of following:
❍
❍
Right-click the icon
or any part of the chart except for the legend and label, then click To
Crosstab on the shortcut menu.
Click Menu > Report > To Crosstab.
2. The Convert Data Fields dialog may appear for your confirmation on converting data fields of the
chart to cube elements of a business/report cube. Click OK to confirm, and the To Crosstab dialog
will be displayed.
3. In the Display tab, select a dimension object
in the Resources box and click
to add it as a
group field to the Columns or Rows box; select a measure object
and click
to add it as an
aggregate field to the Summaries box. Repeat these to add more aggregate fields.
In the Display Name column, you can edit the display name of a group field or aggregate field,
and the Sort columns allow you to specify a sorting manner on a group field.
If you want to remove any group/aggregate field, select it and click
.
To adjust the order of group/aggregate fields, select a group/aggregate field and click
or
.
4. In the Style tab, apply a style to the crosstab as required.
If the chart is in a table or banded object, by default, the crosstab converted from the chart will
take on the style of the table or banded object. If you want to apply another style to the crosstab,
uncheck the Inherit Style option and choose the desired style in the Style box. However, when
there is only one style available, this style will be applied to the crosstab by default and the Style
tab will be hidden from the dialog.
5. Click OK to finish the conversion.
Note: Additional values are supported only in chart. If you convert a chart with additional values into
crosstab, the additional values are not converted together with the chart.
Sorting report data
You can sort the records in a banded object or table, and the groups in a certain group level of the
banded object or table if you have defined one or more group levels. If you want the data of other
types of cube elements to be sorted, you should put the cube element into a banded object or table
and make the data of the cube element inherit from the banded object or table.
●
●
Sorting records: Changing the order of records in the whole banded object or table, or in each
group if there exists one or more group levels. The sorting scope is the whole banded object or table.
Sorting groups at a group level: Changing the order of groups at the specified group level, that
is, the groups will be sorted by value of the first record in each group on the related field. The sorting
scope is the group level.
You can achieve the above by using the Sort dialog, shortcut menu, or labels.
Using the Sort dialog
To set the sort conditions in the Sort dialog:
1. Click Menu > Report > Sort (or the Sort button
Sort dialog.
on the Analysis toolbar) to bring up the
2. From the Sort in Scope drop-down list, select a banded object/table or a group field on which the
sort condition will be based.
3. From the field drop-down list, select the field on which to sort the data, then set the sort order to
Ascend or Descend.
4. If you select a banded object/table in Step 2, you can click
to add a new row of sorting
condition if required. Click
or
to move a row up or down so as to set the sorting priority,
to delete the corresponding sorting condition if it is unwanted.
If what you select in the Sort in Scope drop-down list is a group field, then only one sort condition
can be composed.
To retrieve the opening status of this dialog, click the Reset button.
5. Click OK to accept the settings and to reload the result.
Using the shortcut menu
To sort data on a certain field using shortcut menu:
1. Point to any value of a detail field or group field by which to sort the data in the banded object/
table, and then right-click.
2. Choose the command Sort > Ascend or Sort > Descend from the shortcut menu.
If what you right-click in Step 1 is a detail field value, the sorting will affect the order of detail
records in the banded object or table; if it is a group field value, the order of groups in the group
level represented by the group field will be rearranged.
To remove the sort condition on a field, click Sort > No Sort.
Using labels
You can use a label to control the sorting order for a certain field. This feature needs to be enabled at
report design time.
1. In JReport Designer, select a label in a banded object/table, and then set the Sortable property of
the label to true.
2. Set the field by which you want to sort records as the value of the label's Bind Column property.
3. Save the report and publish it to JReport Server.
beside the label to sort the data. This
4. Run the report in Page Report Studio, and you can click
button will change after you have clicked it, and you can further click it to switch the sorting
direction among ascend, descend, and no sort.
Notes:
●
●
You cannot sort the data by a global type formula.
You can also conduct sorting by using the shortcut menu for a label in the same way as for a field
value, provided you have set its Bind Column property.
●
●
●
●
●
For sorting the data using shortcut menu or labels, you may notice that the corresponding sort
expressions will appear in the Sort dialog if you open this dialog.
If you use the shortcut menu to sort the report data by a field and then sort by another field, the
later sort condition will replace the former one.
JReport allows you to define display names for fields to be showed in the Sort dialog. For detailed
information, see Customizing the field display names in the JReport Designer User's Guide.
You can right-click an object in a banded object and select the Reset item from the shortcut menu to
reproduce the data of the banded object using the data cached in the data buffer. This will clear all
sort and filter conditions except for those predefined in JReport Designer.
Administrators can customize the buffer size for sorting of each report in the Configuration page of
JReport Server so as to improve performance.
Searching for text in a report
You can use the Search dialog to find text in the values of a certain field or in the whole report content.
To show this dialog, click Menu > Edit > Search, click the Search button
on the Standard
toolbar, or right-click a field value or label (or object such as text box) and click Search on the
shortcut menu.
●
To find text in the values of a particular field:
1. Make sure the Search in Whole Report option in the Search dialog is NOT checked.
2. Select the field from the Select Field drop-down list.
3. Set the range with which to search for the value from the Value Range drop-down list.
4. Select the field value you want to search for from the Value drop-down list.
Note: If All is selected in the Value Range drop-down list, the only item in the Value dropdown list will be All and you cannot change the value, in which case, when you submit the
search, JReport will search for all the values of the selected field.
●
Specify whether or not to match case, whether or not to match whole word, whether or not to
highlight all the matching values and the searching direction.
●
Click the Search button.
●
To find text in the report content:
1. In the Search dialog, check the Search in Whole Report checkbox.
2. Type the string you want to search for in the Value box.
3. Set the other options such as the searching direction.
4. Click the Search button.
Notes:
●
●
●
●
Finding text in the values of a particular field is not supported on crosstabs and charts.
If you check Highlight All in the Search dialog, to clear the highlighting in the search result, uncheck
the option and submit the search again, or refresh the report.
If you have not selected the Search in Whole Report option, you will not be able to search special
fields for strings.
JReport allows you to define display names for fields to be shown in the Search dialog. For detailed
information, see Customizing the field display names in the JReport Designer User's Guide.
Working with reports via URL
Besides working on interfaces, most of the Page Report Studio operations such as filter, sort, search, save and so on, can
also be accomplished via URL. When using URLs to access Page Report Studio, you should follow the specifications
described in this section.
The URL in Page Report Studio is:
http://localhost:8888/dhtml?sessionid=XXXXXXX&rptsetid=XXXXXXX&rptname=XXXXXXX&op=...
●
●
●
●
●
●
●
●
http
The web service protocol.
localhost
The host address.
8888
The port.
dhtml?sessionid=XXXXXXX&rptsetid=XXXXXXX&rptname=XXXXXXX&
The path.
?
URL separator.
=
URL separator.
&
URL separator.
op
The key of operation in Page Report Studio.
There are some methods in the file API.js located in <intall_root>\public_html\javascript\dhtml. These methods are
the tools you can use to generate URLs. The result of each of these functions will be a URL.
Parameter
Key
Description
Value
Download Report
Operation
code
op
51
Export
report type
ty
2 for PDF, 3 for PostScript, 4 for RTF, 5 for Text, 6 for Excel, and 7 for XML.
Example
op=51&ty=2
Note
Prototype
●
The order begins with 2.
●
A file of HTML type cannot be downloaded.
function user_downloadReport(type)
Exit
Prototype
function user_exit (popwin)
Navigate Page
Operation
code
op
24
Page number pn
op=24&pn=2
1...n
Example
Note
The page number begins with 1 and is less than total page number.
Prototype
function
function
function
function
user_firstPage()
user_lastPage()
user_nextPage()
user_prevPage()
One Step Filter
Operation
code
op
25
The column
name
col
Mapping the name of a column in JReport.
Operator of
filter
condition
operator
eq (equal to), gt (greater than or equal to), geq (greater than), lt (less than), leq (less than or equal to), neq
(unequal to)
The column
value
value
Logic of
filter
condition
logic
AND, OR, END
Instance
name of the
column
comp
component instance name
Example
op=25&col=CusID&operator=eq&value=1&logic=OR&col=CusName&operator=0&value=ZhangKe&logic=2&comp=convert_sectionObject
Note
The value is case-sensitive.
Prototype
function user_oneStepfilter(columns, operators, values, logics, instanceName)
One Step Search
Operation
code
op
128
The column
name
column
Mapping the name of a column in JReport.
The column
value
value
the value to search for
Whether or
not to
search
content only
isContent
true/false
Whether or
isMatchCase
not to match
case
true/false
The search
direction
true/false
isUp
Whether or
isWholeWord
true/false
not to match
whole word
op=128&column=CusID&value=1&isContent=true&isMatchCase=false&isUp=false&isWholeWord=false
Example
Prototype
function user_oneStepSearch(value, isContent, colName, isUp, matchcase, isWholeWord)
One Step Sort
Operation
code
op
12
The column
name
col
Mapping the name of a column in JReport.
The column
sort order
ord
true/false
Instance
name of the
column
comp
component instance name
Example
op=12&col=CusID&ord=true&col=CusName&ord=false&comp=convert_sectionObject
Note
The value is case-sensitive.
Prototype
function user_oneStepSort(columns, sorts, instanceName)
Open Report
JSP page
/dhtmljsp/dhtml.jsp
Action
jrs.cmd
Report name jrs.report
jrs.try_vw
path/name
Catalog path jrs.catalog
Result type
Example
Note
jrs.result_type
int
http://localhost:8888/dhtmljsp/dhtml.jsp?jrs.report=%2fSampleReports%2fEmployeeInformation.cls
=&jrs.cmdjrs.try_vw&jrs.catalog=%2fSampleReports%2fSampleReports.cat
●
The path delimiter is "/". If you encounter problems, you can replace it with "%2f".
●
The version number can be none, as with the example.
Open RSD File
JSP page
/dhtmljsp/dhtml.jsp
Result path
jrs.path
path/name
Result name
jrs.result
path/name
Result
version
number
jrs.rst_version
Example
http://localhost:8888/dhtmljsp/dhtml.jsp?jrs.resource_path=/USERFOLDERPATH/admin/test&jrs.file=1980996366.rsd
Note
int
●
The path delimiter is "/". If you encounter problems, you can replace it with "%2f".
●
The version number cannot be none.
Redo
Operation
code
op
85
Example
op=85
Prototype
function user_redo()
Refresh
Operation
code
op
83
Example
op=83
Prototype
function user_refresh()
Reset
Operation
code
op
76
Example
op=76
Prototype
function user_reset()
Save Report
Operation
code
op
82
Example
op=82
Prototype
function user_saveRpt()
Search Next
Operation
code
op
Example
op=34
34
Show Export to Dialog
Prototype
function user_showSaveResultDialog()
Show Help
Example
Dialog ID
HELP_OP
182
http://localhost:8888/dhtmljsp/help.jsp?sessionid=XXXXXXX&rptsetid=XXXXXXX&rptname=XXXXXXX&HELP_OP=XXX
Note
The URL gets the body of a window, you should put it as xxx in window.open("xxx", ..)
Prototype
function user_showHelp(helpId)
Show Panel or Dialog
Prototype
function
function
function
function
function
function
function
function
function
function
function
function
function
user_showUserPanel()
user_showTOC()
user_showDHTMLView()
user_showToolbox()
user_showSortDialog()
user_showFilterDialog()
user_showNewRptDialog()
user_showOpenRptDialog()
user_showSaveAsDialog()
user_showPageSetupDialog()
user_showSaveResultDialog()
user_showPageSetupDialog()
user_showPrintDialog()
Undo
Operation
code
op
Example
op=84
Prototype
function user_undo()
84
Zoom
Operation
code
op
50
Proportion
val
op=50&val=250
0~400
Example
Note
val must be an integer between 0 and 400
Prototype
function user_zoom(value)
Opening multiple reports in one session
You can open multiple reports in Page Report Studio in one session. This means that each time you run a page report, it will
open in a new window. Also, when working in the embedded mode, you can assign frames to the reports, so that more than
one page report can be viewed in one window at the same time.
In order to illustrate how to view multiple frames in one window, a demo has been provided for you. Follow the steps below:
1. Go to <install_root>\help\samples\JSPSamples\OpenMultipleReports.
2. Copy the two JSP files in the folder to <intall_root>\public_html\jinfonet.
3. Access JReport Server using http://localhost:8888/jinfonet/test.jsp.
4. From the left panel, browse to the report you want to open and click its name. It will then be displayed in the
corresponding frame.
Tuning Page Report Studio performance
JReport provides you with methods for adjusting Page Report Studio performance. You can limit the
number of page reports open simultaneously in Page Report Studio by setting the Page Report Studio
preferences on the JReport Administration page. Furthermore, you can modify a property file to control
the Action Task Manager, which can improve Page Report Studio service performance.
Limiting the number of simultaneously open reports
Whether or not an open page report interacts with the server, it holds many resources. As a result,
opening many reports will decrease server performance. Thus, JReport allows the administrators to
specify the maximum number of page reports that can be open at the same time in Page Report Studio
so as to prevent large numbers of page reports from being open simultaneously and to improve the
server performance.
To set the maximum number of page reports that can be open at the same time:
1. On the JReport Administration page, click Profile on the system toolbar and then select
Customize Profile from the drop-down menu.
2. Click the Page Report Studio > Properties > Advanced tab.
3. Check the Maximum Number of Open Reports option and type the number to your
requirement in the text box.
4. Click OK upon finishing.
If the number of open reports exceeds the limit, an error page will be displayed prompting you to close
one before opening a new one.
Note: The Maximum Number of Open Reports option works together with the maximum number of
concurrent reports allowed by your product license. Of these two values, whichever is smaller will be
used as the real maximum number of open reports allowed. For example, if the value of the Maximum
Number of Open Reports option is 10, and the number that the license allows is 20, 10 will be used as
the maximum number of page reports that can be opened simultaneously.
Action Task Manager
Some Page Report Studio operations require a large amount of memory and CPU processing power.
The Action Task Manager improves Page Report Studio service performance by preventing a large
number of actions from being run simultaneously.
The Action Task Manager coordinates Page Report Studio actions through two fixed-size tables:
●
●
Concurrent Processing Table - This registers the requests that are currently being processed by
the Page Report Studio service.
Waiting Requests Queue - This registers the requests that are waiting for being processed by the
Page Report Studio service.
Note: Only certain operations that consume considerable hardware resources need to be prevented
from being run at the same time. You can define which kind of requests need to be queued before
being processed.
When a new Page Report Studio request reaches the server, it will be processed according to the
following flow:
1. The Page Report Studio service determines whether the requested operation is a restricted action.
If it is, the Action Task Manager will take over the request. Otherwise, it will be processed directly,
without being managed by the Action Task Manager.
2. If the Concurrent Processing Table is full, the restricted request will be assigned to the Waiting
Requests Queue. If the queue is full, the Page Report Studio service will refuse the request and
return a warning message.
3. After the request has been processed, it will be de-registered from the Concurrent Processing
table. The Page Report Studio service will then automatically continue to process the requests in
the Waiting Requests Queue.
By using the property file dhtml.properties provided in Page Report Studio, you can balance the server
load by adjusting table sizes and specify which kind of requests are managed by the Action Task
Manager.
dhtml.properties
The dhtml.properties file is located at <install_root>\bin. It allows you to control three major
options for the Action Task Manager:
●
Specifying the size of the Concurrent Processing Table
Use queue.actions.max.concurrent=[integer] to set the maximum number of requests that can
be processed simultaneously. The value of this property can be equal to or larger than 0. Use 0
(default) to disable the request queue feature.
●
Specifying the size of the Waiting Requests Queue table
Use queue.actions.max.pending=[integer] to set the maximum number of to-be-handled
requests that the queue can contain. The value of this property can be equal to or larger than 0. 0
means no requests will be stored in the queue. A request will either be handled by the Page Report
Studio service or be rejected when the maximum limit of the Concurrent Processing table has been
reached.
●
Specifying the actions that can be applied for the Page Report Studio Request Queue
feature
These are listed below:
queue.actions.init=false
queue.actions.undo=true
queue.actions.redo=true
queue.actions.drill=true
queue.actions.drillup=true
queue.actions.refresh=false
queue.actions.filter=true
queue.actions.sort=true
queue.actions.search=true
queue.actions.finishNewReport=true
#
#
#
#
#
#
#
#
#
#
Action:
Action:
Action:
Action:
Action:
Action:
Action:
Action:
Action:
Action:
DHTML report initialization
Undo
Redo
Drilling
Drilling up
Refreshing
Filtering
Sorting
Searching
Finishing creating a new report
These properties will only work when the queue feature has been enabled by setting queue.max.
concurrent.actions>0.
True - The action will be handled by the Action Task Manager.
False - The action will not be handled by the Action Task Manager, but be directly processed by the
Page Report Studio service without being queued.
Web Report Studio
JReport provides the web reporting solution for faster and simpler design and creation of reports using
a web browser.
Web reports are viewed using a new interactive viewer called Web Report Studio. Web Report Studio
provides a much nicer end user experience with many powerful features for interfacing with a report
such as changing parameters without re-running the report. In addition, Web Report Studio still
supports exporting the report to all supported output formats.
The data sources that can be used to create web reports are business views that are resources built on
top of queries. Business views are created and managed in JReport Designer (for details, see Business
Views in the JReport Designer User's Guide). In JReport Server, web reports are created via the Web
Report Wizard using a browser and are opened and edited via Web Report Studio.
Using Web Report Wizard, it is easy to create complex reports with multiple components in a tabular
style layout. Web reports also allow for company logo and titles to be placed on the top of the page for
more formal presentation.
A web report template contains only one report and uses .wls as the file suffix. Web reports are stored
in the JReport Server resource system and follow the server resource and version management rules
such as archive policy and permission setting.
JReport Designer supports creating, opening, and editing of web reports (for details, see Web Reports
in the JReport Designer User's Guide). JReport Designer also allows for web reports created on JReport
Server to be downloaded to Designer and further edited.
This chapter covers the following topics to help you better interact with web reports:
●
Why web reports and when to choose them
●
Components supported in web reports
●
Web Report Studio window elements
●
Creating web reports via wizard
●
Editing web reports in Web Report Studio
Note: A JReport Live license for JReport Server is required in order to use web reports and all the
related functions. If you do not have a Live license please contact your Jinfonet Software account
manager to obtain a license. In addition, Web Report Studio cannot run on Internet Explorer 8.
Why web reports and when to choose them
Web Report Studio displays web reports (which are also called web layout reports) that are aimed at
easier and faster report creation and design, faster report execution, easier customization, and better
presentation style using a newer Rich Internet Application (RIA) Web 2.0 interface. Web reports also
support agile development techniques such as continuous integration by allowing report templates to
be updated by both Web Report Studio and JReport Designer.
●
●
●
●
●
●
Fewer functions
Web reports (.wls) support a subset of functions of JReport page reports (.cls). The basic and
essential functions not only guarantee a good report presentation, but also make the report design
experience easier for a new user of JReport.
Single report solution
Only one report in a web report speeds up the report running process as compared to a multiplereport page report.
Tabular style layout
The creation of a page report using the Standard Report Wizard can only create one data component
(table, crosstab, chart, or banded object) using the wizard. The Web Report Wizard provides a
tabular style layout in which you can place a table, crosstab or chart in each tabular cell so as to
achieve a holistic layout with multiple components from the very beginning.
Predefined report templates
Web reports allow you to choose a starting template so you can predefine the template to include
standard features such as company logo, company name, privacy notices or any standard items and
styles you want your users to start with.
Fast report rendering
At runtime, Web Report Studio provides much higher performance when viewed from a browser
compared to viewing a page report using Page Report Studio. Using Page Report Studio, all of the
user action requests must be sent to JReport Server which renders the new page on the server and
updates the browser view. Using Web Report Studio, many of the actions which require only a
change in rendering the view are done locally on the client in the browser. By using Web Report
Studio, JReport Engine is structured so that as much of the processing as possible is completed on
the client side allowing much higher scalability for JReport Server allowing the server to handle more
simultaneous users.
Creation and edition in both JReport Server and Designer
Web reports created using the Web Report Wizard can be downloaded from JReport Server and
edited in JReport Designer and web reports can be created in JReport Designer and published to
server just like .cls reports. However, page reports created using the Standard Report Wizard can
only be edited in the server. Designer can view these reports but not modify them and publish them.
Also, JReport Designer can be used to create web reports which can be run in Web Report Studio on
the server and saved as a template to use in Web Report Studio. JReport Designer cannot directly
create the template but can create the report and then using Web Report Studio, save the report as
a template (.wsld).
●
Standard banded objects not supported
Page reports support standard banded objects which are not supported by web reports.
Components supported in web reports
Components are the objects that you can place in a report. JReport provides a full set of components
that allow you to present and control the report data and presentation in a wide variety of ways.
Web reports support the following report components:
●
●
●
●
●
●
●
●
●
●
●
Labels
A label is an object that contains a string. It is typically a brief description used to identify a field or
other value nearby.
Images
An image is a digital representation of a picture. The following image types are supported in web
reports: .gif, .jpg, and .png.
DBFields
DBFields, or database fields, are fields directly from columns in the database or other data source
such as XML or Java objects.
Formulas
Formulas are calculated from DBFields, other formulas, summaries, and parameters, so they can
present information which is not available directly from the database fields.
Summaries
A summary is a special kind of formula. A summary generates a count, average, sum, standard
deviation or other transformation of a set of data values. A summary applies to a defined group of
data. Summaries are required to provide the data values for charts as well as totals for table reports.
Parameters
A parameter in JReport is a variable whose value is determined at runtime. The runtime parameters
help you dynamically control your report results such as filtering data.
Special fields
Special fields are defined by JReport and allow you to easily obtain system information and reportrelated data and add it to your report. All special fields are supported to insert into web reports in
JReport Designer. However, due to the characteristics of Web Report Studio, only these can be
rendered and edited in Web Report Studio: User Name, Modified Date, Modified Time, Fetch Date,
Fetch Time, Print Date, and Print Time. For more, see Special fields in the JReport Designer User's
Guide.
Web controls
Web controls are report components designed to be similar to the kinds of controls found on web
pages. Currently, the following four web controls are supported in web reports: parameter control,
parameter form control, filter control, and navigation control.
Multimedia objects
Multimedia objects include Flash, Real Media, and Windows Media objects.
Tabular
A tabular is a component designed to lay out other components. There is one and only one tabular in
a web report.
Tables
A table gives you great control over how to present data, including placing fields, grouping them, and
sorting them. It is composed of rows and columns, and each contains several cells. With such a
structure a table is a good way to show any two-dimensional dataset.
●
●
Crosstabs
A crosstab summarizes data and presents the summaries in a compact row and column format.
2-D Charts
A chart organizes and graphically presents data in a way that makes it easy for end users to see
comparisons, trends, and patterns in data. It represents the report data in a visually straightforward
form. A chart is based on the chart platform. On the platform, the chart paper, the legend, and labels
make up the chart. You can create a chart that contains only simple DBFields, or a complicated chart
that contains DBFields, groups, summaries, and even formulas. Normally, DBFields, summaries, and
formulas in a report are represented in a chart using chart data markers, and groups are used to
produce category names and data series names. DBFields can also be used as category names.
For details about chart types, see Chart types in the JReport Designer User's Guide.
For how charts present data, see How data is represented in a chart in the JReport Designer User's
Guide.
For the elements that compose a chart, see Chart elements in the JReport Designer User's Guide.
Tip: In JReport, the components that can be bound with a data source are also referred to as data
components. These components include tables, crosstabs and charts.
Web Report Studio window elements
Here are two ways of accessing Web Report Studio:
By creating a new web report
On the JReport Console > Resources page, click New > Report. In the Select Report Type dialog,
choose Web Report and click OK. Then follow the Web Report Wizard and click Run. Web Report Studio
will then be displayed with the new report.
By running an existing web report
On the JReport Console > Resources page, browse to the target web report and choose the appropriate
way to run the report in Web Report Studio.
Web Report Studio window elements
The main page of Web Report Studio consists of the user information bar, menus, toolbar, left panels
and report area. The options for browsing or controlling a web report are as follows:
Menu/
Toolbar
File
Edit
Button
Tool Name
Description
New Report
Creates a new web report
based on an existing business
view.
Open
Opens a web report.
Save
Saves the changes of the
current web report.
Save As
Saves a copy of the web report
or the report template in the
current web report to server
resources.
Export
Exports the report result to disk
or version in various formats.
Page Setup
Configures the report page
settings.
Print
Prints the report result to a
PDF/HTML file.
Exit
Closes the current web report
and exits Web Report Studio
releasing all of the resources.
Undo
Undoes the last operation.
Redo
Reverses the operation of Undo.
Delete
Deletes the selected object.
Wizard
Opens the report wizard for you
to edit the selected table,
crosstab or chart.
Filter
Filters the report records
according to the filter criteria
you specify.
View
Insert
Format
To Chart
Converts a crosstab into a
chart.
To Crosstab
Converts a chart into a
crosstab.
Rotate Crosstab
Rotates a crosstab to exchange
the axes on the crosstab in
order to create a different view
of the crosstab.
Report Body
Properties
Defines properties of the report
body.
Bind Data
Specifies to bind a data source
to the web report.
Unhide
Components
Shows the hidden components
you specify.
Style
Applies a style to the selected
components or the whole
report.
Editing Marks
Shows or hides editing marks
(dashed outlines for objects
and report body). If the option
is unselected, the editing mark
will not be shown when a
report object receives focus,
and report objects cannot be
moved or resized.
Refresh
Runs the web report using
previously provided
parameters. The Refresh
operation fetches the data
again.
Table
Inserts a table into the web
report.
Crosstab
Inserts a crosstab into the web
report.
Chart
Inserts a chart into the web
report.
Parameter
Control
Inserts a parameter control
into the web report.
Parameter Form
Control
Inserts a parameter form
control into the web report.
Filter Control
Inserts a filter control into the
web report.
Navigation
Control
Inserts a navigation control into
the web report.
Label
Inserts a label into the web
report.
Image
Inserts an image into the web
report.
Multimedia
Object
Inserts a multimedia object
into the web report.
Special Fields
Inserts a special field into the
web report.
Font
Specifies the font format of the
selected text. Available only
when a label or field is selected.
Merge
Merges the selected tabular
cells into one.
Split
Splits the selected tabular cell
into the specified number of
rows and columns.
Language
Help
Standard
Toolbar
Allows you to specify the
language in which to display
the report. Available only when
Enable NLS is checked in the
Profile > Customize Server
Preferences > Advanced panel
on the JReport Console page.
User's Guide
Opens the Web Report Studio
User's Guide.
JReport Home
Page
Connects to JReport Home
Page.
Technical
Support
Accesses Jinfonet Technical
Support.
About Web
Report Studio
Shows product information
about Web Report Studio.
Language
Specifies the language in which
to display the report. Available
only when Enable NLS is
checked in the Profile >
Customize Server Preferences
> Advanced panel on the
JReport Console page.
New Report
Creates a new web report
based on an existing business
view.
Open
Opens a web report.
Save
Saves the changes of the
current web report.
Save As
Saves a copy of the web report
or the report template in the
current web report to server
resources.
Export
Exports the report result to disk
or version in various formats.
Page Setup
Configures the report page
settings.
Print
Prints the current report result
to a PDF/HTML file.
Refresh
Runs the web report using
previously provided
parameters. The Refresh
operation fetches the data
again.
Undo
Undoes the last operation.
Redo
Reverses the operation of Undo.
Filter
Filters the report records
according to the filter criteria
you specify.
Delete
Deletes the selected object.
Quick Format
Toolbar
Context
Toolbar for
Table
Show Objects
Specifies which objects to show
in the report.
Rotate Crosstab
Rotates a crosstab to exchange
the axes on the crosstab in
order to create a different view
of the crosstab.
Swap Chart
Groups
Specifies whether to switch
data between the category and
series axes, or between the
category and value axes of a
chart if there is no field on the
series axes.
Font
Specifies the font format of the
selected text. Available only
when a label or field is selected.
Background
Color
Changes the background color
of the selected text. Available
only when a label or field is
selected.
Align
Makes the selected text left,
center or right aligned.
Available only when a label or
field is selected.
Merge
Merges the selected tabular
cells into one.
Split
Splits the selected tabular cell
into the specified number of
rows and columns.
Table Wizard
Opens the Table Wizard for you
to edit the table.
Show/Hide Detail Hides or shows the detail
columns you specify.
Context
Toolbar for
Crosstab
Context
Toolbar for
Chart
Add/Remove
Group
Specifies whether to add or
remove the selected field as a
group.
Show/Hide
Summary
Specifies whether to show or
hide the selected summary
field.
Hide
Hides the selected column.
Aggregate On
Creates a new summary
directly based on the field
bound with the table detail
column.
Crosstab Wizard
Opens the Crosstab Wizard for
you to edit the crosstab.
Rotate Crosstab
Rotates a crosstab to exchange
the axes on the crosstab in
order to create a different view
of the crosstab.
Chart Wizard
Opens the Chart Wizard for you
to edit the chart.
Panel
Swap Chart
Groups
Specifies whether to switch
data between the category and
series axes, or between the
category and value axes if
there is no field on the series
axes.
Chart Type
Lists all available chart types
for you to change the type of
the chart.
Chart Options
Lists more options for you to
specify the layout of the chart.
Parameters
Lists all the parameters used
by the current report. It is
available when the current
report uses parameters.
Resources
Lists all the available resources.
You can use the quick search
toolbar at the top of the panel
to search for any desired
resources related with the
currently focused component in
a fast and convenient way (to
display the toolbar, click the
Search button
at the
upper right corner of the panel).
Shortcut Menu
Components
Lists all the available
components that can be
inserted into reports.
Filter
Specifies the criteria to filter
the data field. You can also
remove or change existing
filters.
"Go To" Filter
After you perform the go-to-byvalue or go-down actions, the
panel is displayed showing the
filter created by the actions.
You can also click in a table,
crosstab, or chart to show this
panel for the component.
Show
Shows the selected fields.
Apply Style
Applies a style to the selected
component.
Delete
Deletes the selected object.
Autofit
Adjusts the width of table and
crosstab fields according to the
contents.
Hide
Hides the selected object.
Filter
Provides submenu items for
filtering the data in the selected
component or remove existing
filters.
Sort
Provides submenu items for
sorting records on the selected
field in ascending/descending
order, or remove the sort.
Edit Detail Table
Edits the detail table to define
the detail fields of the summary.
Go to Detail
Goes to the detailed
information of the selected
summary.
Link/Edit Link
Links the selected object to a
report, URL or e-mail.
Conditional
Formatting
Adds some conditional
formatting to the currently
selected field.
Go Down
Goes from a group which is
non-bottom level in a
predefined hierarchy to the onelevel-lower group while
applying the current selected
value as a filter condition. See
Go-down for details.
Go Up
Goes from a group which is
non-top level in a predefined
hierarchy to the one-levelhigher group. See Go-up for
details.
Go To
Goes to any group to show its
record information.
Go to By Value
Goes to any group with the
current group value as a filter
to show its record information.
Properties
Defines properties of the
selected object.
Select
Make the corresponding object
selected.
Notes:
●
●
Web Report Studio has two modes: View Mode and Edit Mode, and the toolbar and menu commands
that are available in each mode vary. Administrators can specify the default mode that will be applied
when a report is opened in Web Report Studio in the Profile > Customize Server Preferences >
General tab, and you can switch between the two modes by clicking the View Mode or Edit Mode link
on the Web Report Studio toolbar. However, you will not be able to switch the mode if the Show Link
of View/Edit Mode option in the Profile > Customize Profile > Page Report Studio > Properties >
Default tab is unchecked.
The shortcut menu contents vary with the objects you right-click. The above table only lists some
typical items. The following sections will guide you to use the shortcut menu for any object you may
right-click.
Creating web reports via wizard
On the JReport Console > Resources page, you can directly create a new web report in a folder into
which a catalog containing one or more business views has been published.
To create a web report:
1. Open the folder and select the catalog for the new web report from the Catalog drop-down list,
then click New > Report on the task bar of the Resources page.
2. In the Select Report Type dialog, check the option Web Report and click OK. The Web Report
Wizard is then displayed.
3. In the Page screen, choose a template for the report. Template1 allows for your company logo and
report title to be added. Template2 allows for more such as company name and title and report
sub title. Use
to load your company logo. You can set the font properties for company titles
and report titles using
. Click the Page Setup link to set the page properties. If you are an
administrator with the privilege of publishing resources, you can also create a new template
according to your requirement.
4. In the Layout screen, select the required layout with which you want to create the report. Then, in
the edit layout area, select a tabular cell and select the component you want to display in the cell.
Click the Align drop-down list to set the component to the left, center or right of the cell. Repeat
this to add component to the other cells.
If required, you can split the selected cell horizontally or vertically by clicking the Horizontal Split
or Vertical Split button, merge adjacent cells by selecting them and clicking Merge. You can also
resize the tabular cells by dragging the cell border.
5. In the Bind Data screen, define the specified components (for details about how to define a
component, refer to the specific topic in Inserting components). You can use the Back and Next
buttons to switch between the components.
6. In the Style screen, apply a style to the report.
7. Click Save to save the report to the server resource tree. For details, see Saving the report.
8. Click Run to open the report in Web Report Studio.
See also Web Report Wizard for details about options in the wizard.
Report templates
Web reports allow you to choose a starting template. If you are an administrator with the privilege of
publishing resources, you can save report templates to include standard features such as a company
logo, company name, privacy notices or any standard items and styles you want your users to start
with.
A report template stores information in the page header and page footer as a starting point for a web
report.
Report templates can be saved using the Web Report Wizard or Web Report Studio on the server, by
administrator with the privilege of publishing resources.
The saved report templates will be added into the templates directory on the server <install_root>
\templates, and will be automatically loaded onto the Page screen of the Web Report Wizard for use.
To create a report template from the Web Report Wizard:
The Web Report Wizard provides sample templates for you to define your own templates based on.
1. In the Page screen of the Web Report Wizard, make use of Template1 and Template2 to customize
your own report templates. Template1 allows for your company logo and report title to be added.
to load
Template2 allows for more such as company name and title and report sub title. Use
your company logo. You can set the font properties for company titles and report titles using
.
2. To save the report template from the Web Report Wizard, click the Save button.
3. In the Save As dialog, choose the file type of Web Report Template (*.wsld), and specify a
name for the template in the File Name text field, or select an existing template to overwrite it.
When done, click Save.
4. If you want to further format the template, open a report in Web Report Studio that was created
with the template you want to change, edit the page header and page footer, and then save the
report template using the Save As option (Menu > File > Save As or the Save As button
the Standard toolbar).
on
To create or edit a report template using JReport Desinger or Web Report Studio:
You can make use of JReport Desinger or Web Report Studio on the server to create or edit your report
template, by customizing desired information in the page header and page footer of a web report. Then
save the report template using Web Report Studio on the server via the Save As option (Menu > File
> Save As or the Save As button
on the Standard toolbar).
To rename or remove a report template:
Go to the templates directory on your server <install_root>\templates, then rename or delete the
template file (.wsld). For each template file, there is an image file (.wsld.png) which is used to display
in the templates box of the Page screen of the Web Report Wizard, as a representative of the template.
You will need to rename or delete the image file when you rename or delete the template file.
Editing web reports in Web Report Studio
Web Report Studio is the web oriented page where you view and edit web reports. When a report is
opened in Web Report Studio, by default it is in the view mode which provides only viewing-oriented
functions. If you want to edit the report, click the Edit Mode link on the toolbar to enter the edit mode.
Pick a task from the following:
●
General operations in reports
●
Inserting components
●
Making simple modifications to components
●
Manipulating data components
●
Binding links to objects
●
Using dynamic resources
●
Going through the report data
●
Applying filters
●
Using web controls
●
Adding conditional formats to fields
●
Applying parameters
●
Sorting report data
●
Applying CSS styles
●
Saving the report
●
Exporting/Printing the report result
General operations in reports
You can perform the following general operations in Web Report Studio:
●
Opening another web report
on the Standard toolbar) to display the Select a
Click Menu > File > Open (or the Open button
Report dialog, in which the web reports in the same folder as the current open report are listed.
Select the web report you want to open from the default folder or from another folder, and then click
OK.
●
●
Exiting Web Report Studio
If you want to close the current web report and release the resources, just click Menu > File > Exit
(or the button X on the far right of the toolbar). Do not use the close button on the browser window
as that may not release the resources used by the report.
Undoing/Redoing actions
You can undo or redo some actions. To do this, click Menu > Edit > Undo or Redo (or the Undo
button
●
●
●
●
or Redo button
on the Standard toolbar).
Navigating component data via scrollbar
For tables, crosstabs and charts, you can use the scrollbar to navigate their data if the tabular cell
can not display all data of the component.
Turning component pages
In Web Report Studio, if a table or a crosstab contains more than one page, a navigation bar specific
for the component will be available right below the component. You can use the navigation bar to
view the desired pages: click the corresponding button to go to the first page, the previous page, the
next page, or the last page, or input a number in the text box to go to that page.
Showing/Hiding editing marks
You can use editing marks (dashed outlines of objects) for purposes such as aligning, moving and
resizing. The editing marks are shown by default. To switch the status of the editing marks, click
Menu > View > Editing Marks.
Asking for help
At any time, you can click Menu > Help > User's Guide to open the index page of the Web Report
Studio User's Guide. Furthermore, you can click the Help button in any dialog to show the help
document about the dialog. You can also use the Help menu to access Jinfonet Software website for
more information.
Inserting components
You can insert components into a web report via the Insert menu or via the Components panel on the left of the Web
Report Studio window.
The following table lists the report areas that are valid targets for the various components.
Report Layout Area
Component
Page Header/
Footer
Report Body
Tabular Cell
Table Cell
Chart
Y
Y
Y
N
Crosstab
Y
Y
Y
N
Table
Y
Y
Y
N
Group object
Y
Y
Y
Y
Detail object
Y
Y
Y
Y
Aggregation object
N
Y
N
Y
Formula
Y
Y
Y
Y
Label
Y
Y
Y
Y
Image
Y
Y
Y
N
Multimedia object
Y
Y
Y
N
Web control
Y
Y
Y
N
The following shows inserting a specific component in detail:
Inserting a table
To insert a table into a web report:
1. Locate the place in the report where you want to insert the table.
2. Click Menu > Insert > Table, or drag Table from the Components panel to the destination. The Insert Table dialog
is displayed.
3. Specify a title for the table in the Table Title text field, and if required, click
title.
to set the font properties for the
4. From the Data Source drop-down list, select the business view in the current catalog, on which the table will be built.
If required, click the Filter button to add some filter conditions to the business view to narrow down data displayed in
the table.
5. Select the required table type: Group Above, Group Left, Group Left Above, or Summary Table.
6. In the Display tab, add the required fields from the Resources box to be displayed in the table. Specify the display
name of any added field in the Label column if necessary.
7. In the Group tab, add the group objects
as the grouping criteria, then specify the sorting manner of each group in
the Sort column. To adjust the order of the groups, select a group and click
or
.
8. To add summaries, go to the Summary tab. Select the group to which the summary will be applied, then add an
aggregation object
as the summary field. For the Group Left table, you can use the Row and Column columns to
control the position of the summary field in the table.
9. Click OK to insert the table.
See also Insert Table dialog for additional information about options in the dialog.
Inserting a crosstab
To insert a crosstab into a web report:
1. Locate the place in the report where you want to insert the crosstab.
2. Click Menu > Insert > Crosstab, or drag Crosstab from the Components panel to the destination. The Insert
Crosstab dialog is displayed.
3. Specify a title for the crosstab in the Crosstab Title text field, and if required, click
the title.
to set the font properties for
4. From the Data Source drop-down list, select the business view in the current catalog, on which the crosstab will be
built. If required, click the Filter button to add some filter conditions to the business view to narrow down data
displayed in the crosstab.
5. From the Resources box, select a group object
and click
or
to add it to the Columns or Rows box as a
group field. Then, in the Label column, edit the display name of the group object if required. This will label the row/
column when the report is displayed. By default the Label column is blank and no label will be created for the row/
column. In the Sort column, specify the sorting manner for the group field.
or a numeric detail object
and click
to add it to the Summaries box as an
6. Select an aggregation object
aggregate field. If a detail object is added, specify the aggregate function for it in the Aggregation column. In the
Label column, edit the display name of the aggregate field as required.
7. Repeat this to add more group/aggregate fields. If you want to remove any field, select it and click
order of the fields, select a field and click
or
. To adjust the
.
8. Click OK to insert the crosstab.
See also Insert Crosstab dialog for additional information about options in the dialog.
Inserting a chart
Normally, a chart displays values in a static way and you cannot change the values on it once it is created. However,
JReport provides you with options to make the chart interactive and dynamic. For example, if your data source uses data
that changes quickly over time such as stock market values, you can create a real time chart, so that the chart will update
itself based on a defined interval by using the real time data from the data source. You can make a chart move at runtime
based on the value changes of a motion field by creating a motion chart. In a motion chart, the chart is playable. You can
start or stop the chart to play the dynamic trend of the motion field, control the moving speed of the chart, and if you
create a bubble motion chart, you can even use a trail control to make the chart move showing a bubble or line trail.
In Web Report Studio, when you create a chart, you can choose to make it a common chart, an organization chart, a heat
map, a real time chart, or a motion chart.
To create a common chart:
1. Locate the place in the report where you want to insert the chart.
2. Click Menu > Insert > Chart, or drag Chart from the Components panel to the destination. The Insert Chart dialog
is displayed.
3. Specify a title for the chart in the Chart Title text field, and if required, click
title.
to set the font properties for the
4. From the Data Source drop-down list, select the business view in the current catalog, on which the chart will be built.
If required, click the Filter button to add some filter conditions to the business view to narrow down data displayed in
the chart.
5. To create a single chart, in the Primary Axis box, select the required chart type from the chart type drop-down list.
above the Primary Axis box and an additional chart type will be added. You can
To create a combo chart, click
replace the additional chart type by selecting the required one from the chart type drop-down list. Repeat this to add
more chart types. Check the Secondary Axis checkbox if you want to have the secondary axis (Y2) and define the
chart types on the axis as required. To delete a type, select it and click
.
6. In the Primary Axis or Secondary Axis box, select a chart type and add an aggregation object
value
or an additional
as the data of the type. You can add more than one data field to a chart type. Each added chart type shall
have at least one data field.
If you select a bubble chart type, you need to specify the fields to be shown on the bubble X axis, Y axis and the value
you want to show as the bubble radius in the Show Values box. Note that when you specify a value for the bubble X
axis, this value will be displayed on the category axis instead of the one specified in the Category box. However, the
value defined in the Category box will also be included in data calculation.
To add an additional value to a chart type:
a. Select the chart type in the Show Values box.
b. In the Resources box, expand the Additional Values node, then select Constant Value/Average Value.
c. Click
beside the Show Values box. The Edit Additional Value dialog appears.
d. In the Name text box, specify the display name for the constant/average value.
e. Input the constant value with numeric type in the Value text box, or select a field based on which the average
value will be calculated from the Based On drop-down list.
f. Click OK, and the defined constant/average value will be added to the chart type.
To modify a constant/average value, select the value in the Show Values box, then click
Value dialog, edit the value as required.
. In the Edit Additional
7. Select a group object
in the Resources box and add it to the Category or Series box, the data of which will be
displayed on the corresponding axis.
8. If you want to define some sort order and Select N condition on the category or series field, click
Category or Series box, then define the order and condition in the Category/Series Options dialog.
above the
To define a sort order and Select N condition on the category/series field:
a. In the Category/Series Order box of the Category/Series Options dialog, specify in which order values of the
category/series field will be sorted.
b. In the Category/Series Selection box, specify the Select condition to All, Top N or Bottom N. If All is selected, all
category/series values will be shown in the chart; if Top N or Bottom N is selected, the text field next to it will be
enabled and you can specify an integer here, which means that the first or last N category/series values will be
shown in the chart.
c. Check the Based On checkbox and specify values for the two drop-down lists that follow according to your
requirement.
If Based On is unchecked, the order of the first or last N category/series values will be based on what you specify
in the Category/Series Order box of the dialog; if you check it, the order will be based on values of the summary
field and the sort direction you specify in the drop-down lists next to Based On.
d. If you have selected Top N or Bottom N from the Select drop-down list, you can check the Remaining
Categories/Series In checkbox and then type a character string in the text field, so that the category/series
values beyond the first or last N range will be merged into the group with the name as that character string.
e. If necessary, you can check Skip First, and then input a number M in the text field to the right, then the first M
category/series values will be skipped and the Select N condition will begin with M+1. The skipped values will be
merged into the Remaining Categories/Series group.
f. Click OK to accept the settings.
9. Click OK to insert the chart.
To create an organization chart:
Organization chart, also referred to as org chart, is a one-root-node-tree-structure diagram showing the ownership or
reporting to relations among the nodes which are mapped to a specific entity.
1. Repeat the above steps 1 to 4 for creating a common chart.
2. In the Primary Axis box, select the Org chart type.
3. Select Child in the Org, next select a field from the Resources panel, and then click
the entity.
to add the field for defining
4. Select Parent in the Org, next select a field from the Resources panel, and then click
to add the field for defining
the ownership or reporting to relations among the entity members. For example, if the child field is Employee ID, the
parent field can be the one about IDs showing which employ ID reports to which employ ID. Note that the parent field
should use different one from the child field.
5. The properties panel displays a node model in the org chart. You can add objects including data objects, labels, and
images from the Resources panel into the node by using the
button and then adjust their positions and sizes in
the node and the size of the node if required. Those added objects will be displayed in each node as the information
about the entity members.
6. Click OK to insert the chart.
To create a heat map:
Heat map is composed of rectangles marked by colors and sizes. The rectangles are grouped by group fields. Each
rectangle represents a value of a group field or a combination of values of multiple group fields.
1. Repeat the above steps 1 to 4 for creating a common chart.
2. In the Primary Axis box, select the Heat Map type.
3. Add the fields used to group the data into the Groups box one by one. Use
groups. To remove a group field, select it and click
and
to adjust the order of the
.
4. If you want to define some sort order and Select N condition on a group field, click
above the Groups box. In the
Group Options dialog, specify the order and condition in the same way you do to the category/series field.
5. Add proper summaries into the Summaries box.
The summaries should match the groups. For example, if the groups level is A > B > C, the static summaries grouped
by C can be inserted into the Summaries box, but the static summaries grouped by A, B or other fields cannot.
If no group is specified in the Groups box, you can insert any static summary. And its group-by field will be inserted
into the Groups box automatically.
6. From both Groups and Summaries boxes, specify the fields to do color by and size by, and select the fields as label-by
fields to display in the innermost rectangle in the heat map.
To create a real time chart:
Real time chart is supported on singe bar, bench, line, and area chart types.
1. Repeat the above steps 1 to 4 for creating a common chart.
2. In the Primary Axis box, select a chart type of bar, bench, line, or area, then add the detail objects
objects
or group
of numeric type as the data of the type.
3. Check the Real Time checkbox.
4. By default, Use System Time for Category is checked and you can see the text Use System Refresh Time is displayed
in the Category box, which means the time at which the chart refreshes itself will be used as the category value. You
can uncheck the Use System Time for Category option and add another group object
to be displayed on the
category axis. If you want to define some sort order and Select N condition on the category field you specify, click
above the Category box, then define the order and condition in the Category Options dialog.
5. Specify the time interval at which the chart will get data and refresh itself automatically in the Refresh Interval text
field.
6. Specify the most recent N records to be kept for the real time data on the chart in the Show Most Recent text field.
7. Click the Incremental Fetch button to add the fields you want to use as the unique key of the real time chart in the
Unique Key dialog.
Once a unique key is defined, each time when the real time chart automatically updates itself, duplicated data records
will be filtered out based on the unique key. For instance, if you add the fields Country and Product ID as the unique
key of a real time chart, when a record with the product ID 1 in USA has already been loaded into the chart, no more
records of this product ID in USA will be added to the real time chart because they have the same unique key value.
8. Click OK to insert the chart.
To create a motion chart:
Motion chart is supported on single chart of bar, bench and bubble types.
1. Repeat the above steps 1 to 4 for creating a common chart.
2. In the Primary Axis box, select a chart type of bar, bench or bubble, then add the required aggregation objects
additional values
or
as the data of the type.
If you select a bubble chart type, you need to specify the fields to be shown on the bubble X axis, Y axis and the value
you want to show as the bubble radius in the Show Values box. Note that when you specify a value for the bubble X
axis, this value will be displayed on the category axis instead of the one specified in the Category box. However, the
value defined in the Category box will also be included in data calculation.
3. Select a group object
in the Resources box and add it to the Category or Series box, the data of which will be
displayed on the corresponding axis.
4. If you want to define some sort order and Select N condition on the category or series field you specify, click
above the Category or Series box, then define the order and condition in the Category/Series Options dialog.
of Integer, Date or Time type as the motion field.
5. Check Motion Bar for Playable Chart, add a group object
When the element is of the Date data type, you can define some special function for it by clicking the Special Function
button.
6. Click OK to insert the chart.
When a motion chart is created, you can use the motion control section to make the chart move. Click the play button and
the chart will show its dynamic trend based on the value change of the motion field which is bound in the motion bar. To
stop it, click the button again. You can also control its moving speed by dragging the slider between Slow and Fast on the
speed control. For a bubble chart, you can control whether the chart will be moving in bubble or line trail.
See also:
●
Insert Chart dialog for additional information about options in the dialog.
●
How data is represented in a chart in the JReport Designer User's Guide for how charts present data.
●
Chart elements in the JReport Designer User's Guide for the elements that compose a chart.
●
Chart types in the JReport Designer User's Guide for more information about the chart types.
●
Creating a real time chart in the JReport Designer User's Guide for real time chart example.
●
Creating a motion chart in the JReport Designer User's Guide for motion chart example.
Inserting a label
To insert a label into a web report, locate the place in the report where you want to insert the label, then click Menu >
Insert > Label, or drag Label from the Components panel to the destination. The label will then be inserted in the
specified location.
Inserting an image
To insert an image into a web report:
1. Locate the place in the report where you want to insert the image.
2. Click Menu > Insert > Image, or drag Image from the Components panel to the destination. The Insert Image
dialog is displayed.
3. Specify the image you want to insert.
❍
❍
❍
To use an image in the local file system, select Local File, then click Browse to find the image.
To use an image on a website, select Web URL, then input the image URL or paste the URL in the Image URL text
field.
To use an image in the image library of Web Report Studio, select Library, then select the image in the My Images
box.
4. Click OK to insert the image.
Inserting a multimedia object
1. Locate the place in the report where you want to insert the multimedia object.
2. Click Menu > Insert > Multimedia Object, or drag Multimedia Object from the Components panel to the
destination. The Insert Multimedia dialog is displayed.
3. Choose from the three multimedia object types: Flash, Real Media file, or Windows Media File.
4. In the File Name/URL text field, specify the full path of the multimedia object you want to insert or use the Browse
button to find it if it is on your local disk. Or you can provide a URL for loading it from a website.
5. The Plug-in page text field provides a default URL from which to download the player to play the inserted multimedia
object on a web page.
6. In the Properties box, specify the properties for the multimedia object as required.
7. Click OK to insert the multimedia object.
See also Insert Multimedia dialog for additional information about options in the dialog.
Inserting a web control
You can insert the following web controls into a web report: parameter control, parameter form control, filter control, and
navigation control. For details, see Using web controls.
Inserting a special field
To insert a special field into a web report, do either of the following:
●
●
On the Menu > Insert > Special Fields submenu, click the target special field, User Name for example, then point to
the destination where you want to add the special field and click the mouse button.
Drag the special field from the Components panel to the destination in the report.
Note: When there are multiple data components in a web report, JReport will calculate the data and display the data
components in an appropriate way to avoid missing data in the report as much as possible.
Making simple modifications to components
This section introduces the general actions that you can perform on the report components.
Resizing a component and its elements
To resize a component, click anywhere in the component, then you will see it is surrounded by a rectangle with
resizing handles. Point to a handle, when the mouse pointer turns to a double-headed arrow, you can drag the handle
to resize the component.
To adjust the width of a column in a table, point to the right boundary of the column, when the mouse pointer
becomes a double-headed arrow, drag the handle to resize the column.
To adjust the row height in a table, point to the lower boundary of a row, when the mouse pointer becomes a doubleheaded arrow, drag the handle to resize the row height. Then all the other rows of the same role will be resized too.
For example, if a detail row is resized, all rows in the detail area will be resized. If a group row is resized, all rows of
the group will be resized, while the other groups' rows keep unchanged.
To resize the column or row in a crosstab, drag the right or lower boundary. Then all the columns or rows of the same
role will change too.
For a tabular, point to the boundary between two cells and the mouse pointer will become a double-headed arrow,
you can then drag the boundary to adjust the size of the related cells.
Hiding/showing a component
To hide a component, right-click on the component, then click Hide on the shortcut menu.
For a row, a column, or a header/footer in a table, there are two ways to access the Hide option:
●
●
Right-click any cell within the object, go to the submenu of Table Row or Table Column, then select Hide.
First select the object by right-clicking any cell within the object and selecting Select on the submenu of Table Row
or Table Column, then right-click the object and select Hide.
To show the hidden components, click Menu > Edit > Unhide Components and then select the desired components
to show from the drop-down list. Another way to show the component after hiding is Undo.
For any component whose parent doesn't have a data source, for example, a label in the tabular cell of a web report,
you can also use the Show Objects dialog to show or hide them. To do this:
1. Click the Show Objects button
on the toolbar to display the Show Objects dialog.
2. Select true or false from the Invisible drop-down list to show or hide the corresponding component. You can also
use a formula to control whether or not to to show the component.
3. When done, click OK to accept the settings.
Using formulas to control showing or hiding components
You can use formulas to control whether the components whose parents have no data source will be shown or not in
a web report. However, before doing this, you need to first bind a data source to the web report, then create dynamic
formulas of Boolean type based on this data source and use these formulas to control the Invisible property of the
required components in the Show Objects dialog. A return value of true will hide the component.
To use formulas to control which components to show in a web report, follow the steps below:
1. Click Menu > Edit > Bind Data. The Bind Data dialog is displayed.
2. Select a business view in the current catalog.
3. Click OK to bind the business view to the web report.
4. Click any blank place in the report. The business view bound to the report will be displayed in the Resources
panel.
5. Follow the steps in Creating and using dynamic formulas to create the formulas you need.
6. Click the Show Objects button
on the toolbar to display the Show Objects dialog.
7. Click
beside the Invisible property of the component which you want to control by formula and select the
required formula from the drop-down list. Repeat this to select formulas for other components.
8. Click OK to confirm the settings. Then whether the components will be shown or not will then be determined by
the return value of the specified formulas.
If you set the Invisible property of a component to true using a formula, the object will not be listed in the Menu >
Edit > Unhide Components drop-down list. You can show it only by using the Show Objects dialog. Meanwhile, once
the Invisible property of a component in a web report is controlled by a formula, the data source bound to the web
report cannot be changed unless you remove the relationship between the formula and the property.
For a web report created in JReport Designer, if it has been bound with a data source before being published to
JReport Server, and some dynamic formulas have been created based on this data source:
●
●
If any of the formulas is used by the web report in JReport Designer, you cannot change the bound data source for
the web report in Web Report Studio. However, you can use the formulas of Boolean type created in JReport
Designer or create new formulas based on this data source to control the Invisible property in the Show Objects
dialog.
If none of the formulas is used by the web report in JReport Designer, you can change the bound data source for
the web report in Web Report Studio as you want.
Editing a component
●
●
●
To edit a label, click in the text and update the content. You can also use the Quick Formats toolbar to format the
font, border, alignment, and background color of a label.
To edit a table, crosstab, or chart, use the corresponding component wizard on the shortcut menu. For details, see
Manipulating data components.
To edit an image or a multimedia, click on the component, when the icon
appears at its upper left corner, rightclick on the icon and click Edit on the shortcut menu and then modify the settings in the displayed dialog.
For a tabular, you can edit it as follows:
●
❍
Merging tabular cells
Adjacent cells in a tabular which form a rectangle can be merged into one cell.
To merge adjacent cells, select them one by one while holding the Ctrl key, then click Menu > Format > Merge
or click
❍
on the toolbar, and these cells will be merged into one cell.
Splitting a tabular cell
To split a tabular cell, select the cell and click Menu > Format > Split or click
Split Cell dialog, specify the number of rows and columns and click OK.
on the toolbar, then in the
Modifying component properties
You can modify object properties with the corresponding properties dialog.
●
To format the properties of an object in a report, right-click the object and then select Properties from the
shortcut menu. In the corresponding properties dialog, specify the settings as required.
For a table cell, the Properties option is available on the submenu of Table Cell after you right-click the cell.
For a row, a column, or a header/footer in a table, there are two ways to access the Properties option:
❍
❍
●
Right-click any cell within the object, go to the submenu of Table Row or Table Column, then select Properties.
First select the object by right-clicking any cell within the object and selecting Select on the submenu of Table
Row or Table Column, then right-click the object and select Properties.
If you want to format the properties of the report, click Menu > Edit > Report Body, then in the Report Body
Properties dialog, configure the properties as required.
For detailed explanation about options in the properties dialogs, refer to the specific topics in Web Report Studio
dialogs.
Deleting a component
A component can be removed from the report if it is no longer required. To delete a component, right-click on the
component, then use Delete on the shortcut menu. Then, a message will prompt, asking for your confirmation. Click
Yes in the message box so as to remove the component.
To delete a table column, take one of the following:
Right-click any cell within the column, go to the submenu of Table Column, then select Delete.
●
●
First select the column by right-clicking any cell within the column and selecting Select on the submenu of Table
Column, then do either of the following:
❍
Drag the column to the Resources panel.
❍
Right-click the column and select Delete.
Note: In a web report, there must be one and only one tabular, so you cannot either insert another tabular or delete
the current tabular.
Manipulating data components
You can manipulate data components, which refer to tables, crosstabs, charts and geographic maps, in Web Report Studio as
shown below. Note that, most of the manipulations require selecting the component first. To select a component, click
appears at its upper left corner, click the icon.
anywhere in the component, when the icon
Manipulating a table
●
Changing the table definition
1. Select the table and do one of the following to display the Table Wizard.
■
Click Menu > Edit > Wizard.
■
Click the Table Wizard button
■
Right-click the icon
on the Context toolbar.
of the table and select Table Wizard from the shortcut menu.
2. In the Table Title text field, edit the title of the table. You can click
title.
to customize the font, size, and style of the
3. Click the Filter button to apply some filter conditions to narrow down data displayed in the table.
4. In the Display tab, add or change the fields displayed in the table.
5. In the Group tab, modify the grouping criteria of the table.
6. Upon finishing, click OK to apply the modifications.
For details about how to define a table, see Inserting a table.
●
Switching table column fields
In addition to the above method, another more convenient way to change the fields displayed in the detail columns or
group columns of a table is by using the Switch command.
❍
❍
●
To change the field in a detail column:
Right-click the detail column and select Table Column > Switch Column from the shortcut menu, or select the detail
column, right-click it and select Switch Column from the shortcut menu. The fields available for the detail column are
listed in the submenu with the current used field checked. Select the field you want to use to replace the current one in
the column.
To change the field in a group column:
Right-click the group field and select Switch Group from the shortcut menu. The fields available for the group column
are listed in the submenu with the current used field checked. Select the field you want to use to replace the current one
in the column.
Adding or removing a table column or group by dragging
To drag a field into a table to become a table column, drag it from the Resources panel and then move the cursor on the
column header to the border of an existing table column until a highlighted vertical line appears, then release the cursor,
and the new column will be placed where the highlighted line lies.
To drag a group field into a table to become a group, drag it from the Resources panel and then move the cursor in the
detail section or to the border of an existing table group until a highlighted horizontal line appears, then release the cursor,
and the new group will be placed where the highlighted line lies.
To remove a table column, first select it, next drag and drop it to the Resources panel, and then confirm the removal.
●
●
●
Adjusting order of columns in a table
The order of columns in a table can be easily adjusted. To do this, first select a column by right-clicking any cell within the
column and selecting Select on the submenu of Table Column, then drag it to the left or right boundary of another column,
when a highlighted line appears along the column boundary, release the mouse button, and you will see the order changes.
Adjusting the width of table columns according to contents
When the contents in cells of a table column need more space to completely display, you can adjust the width of the table
column according to the contents. To do this, right-click the column and select Table Column > Autofit from the shortcut
menu.
Aggregating on a detail column
You can summarize the data in a detail column. To do this:
1. Right-click the detail field and select Aggregate On from the shortcut menu. Or you can first select the column by
right-clicking any cell within the column and clicking Select on the submenu of Table Column, then on the Context
toolbar, click the Aggregate On button
.
2. In the Aggregate On dialog, specify a function from the Function drop-down list to summarize the data.
3. When done, click OK.
■
■
If the table has groups, you will find data in each group level and the whole table are summarized respectively in the
column.
If the table has no groups, the summary will be based on the whole table.
When you finish summarizing a detail column, you will find a dynamic aggregation is created at the same time which is
given a default name Function_DetailFieldName in the Dynamic Resource > Aggregations list in the Resources panel and
you can use it again in the current report if required.
●
Adding/Removing groups in a table
You can add more groups into a table or remove the groups that are not required from a table.
❍
To add a group into a table:
and you will get a drop-down
Select the table, then on the Context toolbar, click the Add/Remove Group button
list of fields in the business view that can be used as group by fields. From the list you can select the field you would like
to add into the table as a group. If there is no existing group in the table, the added group will be placed at the leftabove position. If the table already contains groups, the new group will be added as the highest level group and follow
the same position pattern as the closest existing group.
❍
To remove a group from a table:
Right-click a field of the group and select Delete from the shortcut menu, then click Yes in the message dialog to
on the Context toolbar of the table: unselect
confirm the removal. Or you can use the Add/Remove Group button
the group you want to remove from the drop-down list, then click Yes in the message dialog.
Showing/Hiding detail columns
●
To show/hide a detail column, select the table, then on the Context toolbar, click the Show/Hide Detail button
From the drop-down list, select/unselect the field name to show/hide its detail column.
.
You can also hide a detail column by one of the following:
❍
❍
First select the column by right-clicking in the column and selecting Select on the submenu of Table Column, then do
either of the following:
■
Click the Hide button
■
Right-click the column and select Hide.
on the Context toolbar.
Right-click in the column and select Table Column > Hide from the shortcut menu.
Showing/Hiding summaries
●
To show/hide a summary from a table, first select the table and then do either of the following:
❍
❍
●
On the Context toolbar, click the Show/Hide Summary button
summary field name to show/hide it.
. From the drop-down list, select/unselect the
Right-click the icon
of the table, then on the shortcut menu, select/unselect the summary field name from the Show >
Table Column submenu to show/hide it.
Customizing the field value data format
To customize the data format of the values of a field in a table, right-click on any value of the field, then select a format
from the Format submenu, or input a format in the text box at the bottom of the submenu and click Enter on the keyboard.
Manipulating a crosstab
●
Changing the crosstab definition
1. Select the crosstab and then do one of the following to display the Crosstab Wizard.
■
Click Menu > Edit > Wizard.
■
Click the Crosstab Wizard button
■
Right-click the icon
on the Context toolbar.
of the crosstab and select Crosstab Wizard from the shortcut menu.
2. In the Crosstab Title text field, edit the title of the crosstab. You can click
of the title.
to customize the font, size, and style
3. Click the Filter button to apply some filter conditions to narrow down data displayed in the crosstab.
4. Change the fields and summaries used by the crosstab.
5. Upon finishing, click OK to apply the modifications.
For details about how to define a crosstab, see Inserting a crosstab.
●
Switching crosstab fields
In addition to the above method, another more convenient way to change the fields in a crosstab is by using the Switch
command. To do this, right-click a row/column/summary and select Switch Row/Switch Column/Switch Summary from
the shortcut menu. The fields available for the row/column/summary are listed in the submenu with the current used field
checked. Select the field you want to use to replace the current one.
●
Adding or removing a row/column header or an aggregation by dragging
To drag a group field into a crosstab to become a column header, drag it from the Resources panel and then move the
cursor to a border of a column header until a highlighted horizontal line appears, then release the cursor, and the new
column header will be placed where the highlighted line lies.
To drag a group field into a crosstab to become a row header, drag it from the Resources panel and then move the cursor
to a border of the row header until a highlighted vertical line appears, then release the cursor, and the new row header will
be placed where the highlighted line lies.
To drag an aggregate field into a crosstab to become an aggregation, drag it from the Resources panel and drop to the
aggregation section.
To remove a row/column header or an aggregation from a crosstab, first select it, next drag and drop it to the Resources
panel, and then confirm the removal.
●
Converting a crosstab into a chart
1. Select the crosstab and then do either of the following to display the To Chart dialog.
■
Click Menu > Edit > To Chart.
■
Right-click the icon
of the crosstab and select To Chart from the shortcut menu.
2. In the Title text field, input a title for the chart. You can click
to customize the font, size, and style of the title.
3. The Resources box lists all the view elements used in the selected crosstab including group and aggregation objects.
The chart can only be defined based on the view elements listed. Select the required chart type from the chart type
drop-down list. Add a group object
from the Resources box to the Category box, and so to the Series box, and
to the Show Values box respectively.
aggregation objects
If you select a bubble chart type, you need to specify the fields to be shown on the bubble X axis, Y axis and the value
you want to show as the bubble radius in the Show Values box. Note that when you specify a value for the bubble X
axis, this value will be displayed on the category axis instead of the one specified in the Category box. However, the
value defined in the Category box will also be included in data calculation.
4. Click the OK button to finish the conversion.
For details about how to define a chart, see Inserting a chart.
●
Rotating a crosstab
Columns and rows in a crosstab can be exchanged. This operation is called rotating a crosstab.
To rotate a crosstab, first select it, and then do one of the following:
●
●
❍
Click Menu > Edit > Rotate Crosstab.
❍
Click the Rotate Crosstab button
❍
Right-click the icon
on the Context toolbar.
of the crosstab and select Rotate Crosstab from the shortcut menu.
Adjusting the width of crosstab fields according to the contents
When the contents in the field of a crosstab need more space to completely display, you can adjust the width of the field
according to its contents. To achieve it, right-click the field and select Autofit from the shortcut menu.
Customizing the field value data format
To customize the data format of the values of a field in a crosstab, right-click on any value of the field, then select a format
from the Format submenu, or input a format in the text box at the bottom of the submenu and click Enter on the keyboard.
Manipulating a chart
●
Changing the chart definition
1. Select the chart and then do one of the following to display the Chart Wizard.
■
Click Menu > Edit > Wizard.
■
Click the Chart Wizard button
■
Right-click the icon
shortcut menu.
on the Context toolbar.
of the chart, or right-click on the chart platform or paper, then select Chart Wizard from the
2. In the Chart Title text field, edit the title of the chart. You can click
title.
to customize the font, size, and style of the
3. Click the Filter button to apply some filter conditions to narrow down data displayed in the chart.
4. Change the values displayed on the chart.
5. Upon finishing, click OK to apply the modifications.
For details about how to define a chart, see Inserting a chart.
●
Switching chart fields
In addition to the above method, another more convenient way to change the fields displayed on a chart is by using the
Switch command.
❍
❍
To change the field on the category/series axis:
of the chart or right-click on the chart platform or paper, then select Switch
Select the chart, right-click the icon
Category/Switch Series from the shortcut menu. The fields available for the category/series axis are listed in the
submenu with the current used field checked. Select the field you want to use to replace the current one on the axis.
To change the field on the value axis:
of the chart or right-click on the chart platform or paper, then select Switch
Select the chart, right-click the icon
Value from the shortcut menu. The fields available for the value axis are listed in the submenu with the current used
field checked. Click an unchecked field to add it to the value axis.
If a chart has multiple fields on its value axis, you can also click the up or down arrow beside the current used fields to
adjust their order, or click a checked field to remove it from the chart. When there is only one field on the value axis, it
cannot be removed.
For a combo chart, you can change the fields displayed on the chart one by one for each chart type.
●
●
●
Formatting chart elements
You can format the chart graph, platform, paper, legend, X and Y axes, wall, floor, gridlines, and rectangles and rectangle
titles of heat maps using the corresponding format command on the shortcut menu of a chart. For details about the
element properties, refer to the specific format dialog in Web Report Studio dialogs.
Sorting category/series labels
You can sort the labels on the category or series axes of a chart in either descending or ascending alphabetical order. To do
of the chart or right-click on the chart platform or paper, then on the shortcut
this, select the chart, right-click the icon
menu, select the required order from the Sort Category or Sort Series submenu.
Swapping chart groups
You can switch data between the category and series axes, or between the category and value axes of a chart if no field on
the series axes.
To swap the chart groups, first select the chart, then do either of the following:
❍
❍
●
Click the Swap Chart Groups button
Right-click the icon
shortcut menu.
on the Context toolbar.
of the chart, or right-click on the chart platform or paper and select Swap Chart Groups from the
Converting a chart into a crosstab
1. Select the chart and then do either of the following to display the To Crosstab dialog.
■
■
Click Menu > Edit > To Crosstab.
Right-click the icon
shortcut menu.
of the chart, or right-click on the chart platform or paper and click To Crosstab on the
2. In the Title text field, input a title for the crosstab. You can click
title.
3. Select a group object
in the Resources box and click
or
to customize the font, size, and style of the
to add it as a group field to the Columns or Rows
box; select an aggregation object
or a detail object
and click
to add it as an aggregate field to the
Summaries box. If a detail object is added, specify the aggregate function for it in the Aggregation column. Repeat this
to add more group and aggregate fields.
In the Label column, you can edit the label of a group field or aggregate field, and the Sort column allows you to
specify a sorting manner on a group field.
If you want to remove any group/aggregate field, select it and click
.
To adjust the order of group/aggregate fields, select a group/aggregate field and click
or
.
4. Click OK to finish the conversion.
●
Showing/Hiding the chart legend or legend label
of the chart or right-click on the chart platform or paper, then select the
Select the chart, right-click the icon
corresponding Show or Hide command from the shortcut menu to show or hide the legend or legend label. However, the
legend will always be displayed at the exporting or printing results.
Changing chart type
●
Select the chart, then on the Context toolbar, click the Chart Type button
desired chart type and its subtype.
. From the drop-down menu, select the
Showing/Hiding labels on the X/Y axis
●
Select the chart, then on the Context toolbar, click the Chart Options button
Label submenu, then select/unselect the desired labels to show/hide them.
. From the drop-down menu, go to the
Showing/Hiding X/Y gridlines
●
Select the chart, then on the Context toolbar, click the Chart Options button
. From the drop-down menu, go to the
Gridlines submenu, then select/unselect the desired gridlines to show/hide them.
When gridlines are shown, it is better to also have the wall shown so as to make the background gridlines more intuitive.
To show the wall, follow the steps above, then on the Gridlines submenu, select Wall.
●
Changing the chart legend position
Chart legend can be placed at the top, bottom, left or right position in a chart. To change the legend position, select the
chart, then on the Context toolbar, click the Chart Options button
submenu and select the desired position.
●
. From the drop-down menu, go to the Legend
Zooming in chart values
For a bar, bench, line, area or stock chart, you can select the values you are interested in to have them zoomed in. To do
this, drag the mouse from the start value to the end value you want to select, then release the mouse. The selected values
will be zoomed in. If you want to return to the initial status, just click the return button
the chart paper.
●
●
on the upper right corner of
Customizing the data format of chart data labels
You can customize the data format of the legend entry labels and data labels on the category and series axes if they are of
Number or Date/Time type. To do this, right-click on any label and select the required format from the Format submenu, or
input a format in the text box at the bottom of the submenu and click Enter on the keyboard.
Stopping or resuming a real time chart from refreshing
For a real time chart, you can stop or resume it from automatically refreshing by right-clicking it and selecting the Pause
Refresh or Resume command from the shortcut menu.
Notes:
●
●
●
The org chart type cannot be converted to any other chart type, and vice versa. Crosstabs cannot be converted to the org
chart type, and vice versa.
Additional values are supported only in chart. If you convert a chart with additional values into crosstab, the additional
values are not converted together with the chart.
You cannot zoom in chart values if your report is running in the Edit Mode of Web Report Studio. The action can only be
performed in the View Mode.
Manipulating geographic map group markers/areas
Going up/down on geographic map group markers/areas
●
❍
❍
●
For the group level that is higher than some other group levels in a geographic map component, point to its group
marker/area, right-click it and select Go Down from the shortcut menu to jump one group level down.
For the group level that is lower than some other group levels in a geographic map component, point to its group marker/
area, right-click it and select Go Up from the shortcut menu to jump one group level up.
Showing/Hiding geographic map group markers/areas
By default, all visible group markers/areas are shown. To hide them, right-click the geographic map (not the group markers/
areas) and select Hide Markers/Hide Areas from the shortcut menu. If you want to show them again, right-click the
geographic map and select Show Markers/Show Areas from the shortcut menu.
Binding links to objects
You can bind links to labels, images, DBFields, formula fields, parameter fields, special fields, and data
markers on charts of bar, bench, pie, line and area types. The link can either be a simple link or a
conditional link. With conditional link, different targets can be loaded based on different conditions.
However, conditional link is not supported on charts and independent labels that are not bound with a
dataset.
To bind a simple link to an object:
1. Right-click the object and click Link on the shortcut menu to display the Insert Link dialog.
2. From the Link Type drop-down, select the target to which the object will be linked.
❍
❍
Report
If you create a link to a report, when viewing the result, you can view another report by clicking
the object.
URL
Enter the URL in the Hyperlink box if you want to create a link to a web page. If needed, click
the Add Dynamic Field button to insert fields into the URL to compose a dynamic URL. Then
specify the window or frame in which to load the location specified by the URL.
For example, if your report contains a Country field, you can bind a link on the field and
compose a URL as follows: type in http://www.google.com/search?q= into the Hyperlink
text box, then click the Add Dynamic Field button to insert the field Country at the end of the
URL. Then when you click on a country name, a web page specific to this country will be opened.
❍
E-mail
Enter the e-mail address in the Hyperlink box. If needed, click the Add Dynamic Field button
to insert fields into the hyperlink to compose a dynamic e-mail address.
3. When done, click OK to create the link.
To bind a conditional link to an object:
1. Right-click the object and select Link from the shortcut menu to display the Insert Link dialog.
2. Check the Conditional Link checkbox.
3. Click the button
to open the Edit Conditions dialog to define a condition using either simple
expressions or complex expressions according to your requirements.
The newly added condition will then be displayed and highlighted in the conditions box in the
Insert Link dialog.
4. From the Link Type drop-down, select the target to which the object will be linked under this
condition.
5. Repeat the above steps to add more conditions and define the link target for each condition.
To edit a condition, select the condition in the Condition box, then click
dialog, edit the expressions as required.
. In the Edit Conditions
To remove a condition and the corresponding format, select the condition in the Condition box and
click
.
To adjust the priority of a condition, select the condition in the Condition box and then click
or
.
6. When done, click OK to finish defining the conditional link.
See also Insert Link dialog for additional help about options in the dialog.
Once a link is added to an object, you can further edit it or remove it.
●
●
To edit a link, right-click the object and select Edit Link from the shortcut menu. In the Edit Link
dialog, edit the link according to your requirement.
To remove a link from an object, right-click the object and click Remove Link on the shortcut menu.
In the warning message dialog, click Yes to confirm the removal.
Linking a report to another report
A report can be linked to another report, after which the trigger object in the primary report can be
clicked in order to jump to the linked report to obtain information about the trigger object.
1. In the Insert Link dialog, select Report as the link type.
2. Click the Browse button beside the Report text field to specify the target web report you want as
the linked report.
3. Specifies the window or frame in which to load the linked report from the Target drop-down list.
4. Click the Advanced button to displays the advanced settings.
5. In the Conditions tab, click
above the Components box to specify which components in the
linked report will be interlinked with the primary report.
6. Select a component in the Components box, then specify the link relationship for the selected
target component in the Field Conditions box as follow:
a. Click the button
above the Field Conditions box, then a new condition row will be added.
b. Select a field from the drop-down list in the Fields(Primary) column.
c. Choose an operator from the drop-down list in the OP column. The operator can be "=",
"<>", "<", ">", "<=", ">=", or "IN".
d. Specify the field of the linked report from the drop-down list in the Fields(LinkedReport)
column. All fields in the linked report of the same value type as the selected primary report
field will be available.
e. If necessary, you can specify more link conditions by clicking the button
and then
specifying the primary report field, the operator, and the corresponding field in the linked
report. Note that the relationship among these link conditions is AND, which means that
JReport will fetch linked report data which meets all of the conditions.
f. Repeat the above steps to set link conditions for other target components.
7. From the Default Linked Component drop-down list, select which component in the linked report
will be linked with the primary report by default. Then, when the primary report is opened in
HTML, PDF or Excel format, or in Web Report Studio, the page where the data that meet the
predefined condition in the specified component in the linked report will be displayed by default
after you click the link.
8. If the linked report uses parameters, go to the Parameters tab, the Target Report Parameters box
lists the parameters of the linked report. You can assign fields of the primary report to the
parameters. Then, when running the linked report from the link, the field values of the primary
report will be assigned to the parameters automatically.
9. Click OK to apply the settings.
Then, when the primary report is run in Web Report Studio, or in HTML, PDF or Excel format with Run
Linked Report being selected, the link will be enabled, and when you click the trigger object in the
primary report, you will find that the linked report is displayed according to the specified link conditions.
If the linked report is opened in the same frame as the primary report in Web Report Studio, you can
click
on the toolbar to go back to the primary report. Click
next to
and you will get a dropdown list which lists the original report and the linked targets you have just visited within the link
chain. The item checked on the drop-down list is the currently opened page. Select an unchecked item
and you will be directed to that target.
Notes:
●
●
When linking reports, you need to avoid link loops. For example, if you have linked report A to report
B, then you cannot link report B back to report A again.
The conditions specified in the Condition tab are used for setting up the searching criteria between
the two linked reports, which means after you click the trigger object in the primary report, the
pages containing the data that meet the conditions in the linked report will be displayed. However,
when running the primary report in Web Report Studio or JDashboard, the conditions are used for
filtering, that is, only the data that meet the conditions in the linked report will be displayed.
●
For web reports created in JReport Designer which contain links, if the trigger objects of the links
happen to be in some hierarchies (which means you can also perform the go-down action on the
objects by single click), you can click the trigger objects to directly open the links in Web Report
Studio only when the click priority of the link action is specified to be the highest at report design
time. If the priority of the go-down action is specified the highest, you can click the trigger objects to
open the links only when you have reached the lowest level of the hierarchies by going down on the
objects first.
Using dynamic resources
When you add fields to a report, sometimes you may find that the view elements that have been predefined in the business view cannot meet your
requirements, in which case, you can create some dynamic resources and use them in the report to get the desired data. Then when you save the report, the
dynamic resources will be saved along with the report as its resources.
Dynamic resources are report level resources, which means they are only available to the report for which they are created.
Dynamic resources that can be used in web reports include formulas and aggregations.
Creating and using dynamic formulas
You should have some knowledge of the formula syntax before you can successfully compose a formula with no errors. To learn the formula syntax, refer to
Formula syntax.
To create a dynamic formula:
1. In the Resources box of the report wizard, expand the Dynamic Resource > Formulas node, then click <Add Formula•gt; to display the Formula
Editor.
2. Enter a name for the formula in the Formula Name text field.
3. Compose the formula by selecting the required fields, functions and operators from the Fields, Functions and Operators boxes. You can also write the
formula by yourself in the editing box.
For details about the functions and operators, refer to Built-in functions and Operators.
4. Click the Check button
to check whether or not the syntax of your formula is correct.
5. When done, click the OK button to create the formula. You can then use the formula in the report.
Once a dynamic formula has been created, you can then drag it from the Resources panel to the desired position in the report as a detail object, or use it
when working with the report wizard.
Also, if you want to further edit an existing dynamic formula or remove any formula that is not required, right-click the formula and then click the
corresponding command on the shortcut menu.
Notes:
●
You can only use JDK (not JRE) to compile formulas created in JReport and save a dynamic formula with no errors into a web report.
●
Currently, global variables are not supported in dynamic formulas.
●
When formulas reference display names or mapping names, the names should not contain any of the following characters if the names are not quoted by
double-quotation marks "":
"~", "`", "!", "@", "#", "$", "%", "^", "&", "*", "(", ")", "-", "+", "=", "{", "}", "[", "]", "|", "\\", ":", ";", "\", " ' ", "<", ",", ">", ".", "?", "/"
Examples:
❍
Expression @Customer#; will cause a syntax error. But @"Customer#" is ok.
❍
If a field has the display name Category.Aggregation, when adding it to a formula, quote it as "Category.Aggregation" or "Category"."Aggregation".
Creating and using dynamic aggregations
In Web Report Studio, you can also create dynamic aggregations by mapping them to the available resources such as group objects, detail objects in the
current business view and the dynamic formulas that have been created in the report.
To create a dynamic aggregation:
1. In the Resources box of the report wizard, expand the Dynamic Resource > Aggregations node, then click <Add Aggregation•gt;. The Add
Aggregation dialog is then displayed.
2. In the Aggregation Name text field, specify the display name of the dynamic aggregation.
3. Click the button
next to the Resource Name text field to specify the field on which the dynamic aggregation is based.
4. From the Aggregate Function drop-down list, specify the aggregate function.
5. When done, click OK to create the dynamic aggregation. You can then use the aggregation in the report
Once a dynamic aggregation is created, you can then drag it from the Resources panel to the desired position in the report to see the desired data, or use it
when working with the report wizard. And if you want to edit any dynamic aggregation or delete it, right-click the aggregation and click Edit or Delete on the
shortcut menu.
Going through the report data
In a web report, you can choose to show certain groups of records according to your requirements, and switch among the
groups to see the data you want.
●
●
●
●
●
Go-to
Enables you to obtain a different view of data by switching among groups.
Go-to-by-value
Enables you to filter data based on a go-to action to obtain a more detailed view of the data.
Go-down
Enables you to drill data to a lower-level group according to predefined hierarchies.
Go-up
Enables you to drill data to a higher-level group according to predefined hierarchies.
Going to detail
Enables you to concentrate on the details of a group.
After a "going" action has been performed, the data presented in the component will be re-loaded from the data buffer,
showing only the records in the selected group, and the new report created can be viewed, printed, and exported to
other formats in the same way as the original report.
Assume you have created a chart report of Clustered Bar 2-D type on the business view WorldWideSalesBV in Data
Source 1 of the SampleReports catalog in the Webdemo folder, which shows product sales information with Region as the
field on the category axis, Sales Year as the field on the series axis, and Total Sales as the field on the value axis, and
applies the default style to the chart. The chart shows as follows:
The business view WorldWideSalesBV has defined the following hierarchical relationship: Region > Country > State >
City.
We will now take the chart as an instance to illustrate the going functions.
Go-to
The go-to action enables jumping to a different group by replacing the current. It is performed on chart categories and
series.
1. Right-click any value of Region, Asia-Pacific for example, and choose Go To from the shortcut menu. The list of
groups available for "Go to" will appear on the submenu.
2. Click State on the submenu, then in the regenerated result, we can see that State becomes the group for categories
and Sales Year remains the group for series.
3. To return to the original status, click the Undo button
on the toolbar.
Go-to-by-value
The go-to-by-value action allows showing the information of another group while applying the current value being clicked
on as a filter condition. It is performed on crosstab column/row headers, table groups, and chart categories and series.
1. Go back to the original report in the above example.
2. Right-click the value Asia-Pacific of the Region group, and point to Go to By Value on the shortcut menu. A
submenu for the command is displayed, which lists the same items as those of Go To.
3. Click State too and the result will be regenerated.
We can see that the result is different from that of go-to. This is because that, for the go-to-by-value action, the
group of categories changes to State while being filtered by the Region value Asia-Pacific. That is, on the basis of
the go-to action, a filtering action where Region = Asia-Pacific is performed at the same time, and thus the result of
go-to-by-value is generated.
In addition, when a go-to-by-value action is performed, the "Go To" Filter panel will be displayed on the left of the
Web Report Studio window, showing the group and the value that the filter is based on.
4. To go back to the original report, click the Undo button
on the toolbar.
Go-down
The go-down action allows going from a non-bottom level group to the one-level-lower group while applying the current
selected value as a filter condition. It is performed on table groups, crosstab column/row headers, and chart categories
and series.
1. Go back to the original report in the above example, right-click the value Asia-Pacific, on the shortcut menu, point
to Go Down, and we can see that Country is listed as the submenu item.
2. Click Country to see the result. It displays the data about countries in the Asia Pacific region.
3. The one-level-lower group for Country defined in the hierarchy is State. Now click China directly and JReport will go
down to State.
After these two go-down actions, we can see two filters are added in the "Go To" Filter panel, Region = Asia-Pacific
and Country = China.
This is because, when you perform a go-down action, a filter will be created based on the value you click on. In this
example, we first click on the Asia-Pacific region, so JReport drills this region one-level down to display countries in
Asia Pacific, and thus the filter Region = Asia-Pacific is created. If you want all data in the one-level-lower group to
be displayed when you drill down a group, you can remove the corresponding filter from the "Go To" Filter panel, by
clicking X beside the filter condition.
Go-up
The go-up action allows jumping from a group which is non-top level in a predefined hierarchy to the one-level-higher
group. It is performed on table groups, crosstab column/row headers, and chart categories and series.
1. Based on the report result after go-down, right-click any value of State, Beijing for example, on the shortcut menu,
point to Go Up, and we can see that Country is listed as the submenu item.
2. Click Country to see the result. Country is now the group for categories and the filter condition Country = China is
removed from the "Go To" Filter panel.
3. The one-level-higher group for Country defined in the hierarchy is Region. Now right-click any value of Country,
Singapore for example, on the shortcut menu, point to Go Up and click Region, the chart restores to the original
state.
Going to detail
The go-to-detail action is performed on the summary of the tables, crosstabs and charts. First define a table and make it
contain the information you would like to view about the summary values. Suppose that the summary is total sales in
different countries. Then when you perform go-to-detail action on the value of total sales in France, you will get the table
displaying the fields you defined and having applied the filter condition Country=France. When you go to detail of the
total sales in another country, the table will display the data of that country.
To define the detail table for a summary and perform the go-to-detail action on it:
1. Right-click any summary value (for a chart it is any data marker) and select Edit Detail Table from the shortcut
menu. The Edit Detail Table dialog is displayed.
2. From the Resources box, add the fields you want to display in the detail table of the summary. To adjust the order
of the added fields, click
or
.
3. Click OK to finish defining the detail table.
4. Right-click a summary value of which you would like to view the detailed information, then click Go to Detail on the
shortcut menu. The detail table for the summary value will then be displayed, which shows the fields you have
defined.
5. To go back to the original report, click
on the toolbar.
Notes:
●
If the table type is Group Above, you can right-click its group header to show the shortcut menu so as to use the going
function. For other table types, you have to right-click the group name in group column to perform going.
●
The Going feature is not supported on org charts.
●
When performing the go-down action, if the group objects are also defined with some links,
❍
❍
For web reports created in JReport Designer, you can go down to the next level with a single click only when the click
priority of the go-down action is specified to be the highest at report design time. Otherwise, you have to use the Go
Down command on the objects' shortcut menu to perform the action.
For web reports created in Web Report Studio, you can only use the Go Down command on the objects' shortcut
menu to perform the action. The link action takes the highest click priority by default and cannot be edited.
Applying filters
You can apply filters to business views and data components such as tables, crosstabs and charts of a web
report so as to narrow down the data displayed in the web report.
Applying filters to business views
When creating web reports, you can choose to apply some filter to the specified business view to narrow down
the data scope of the data component using the business view.
In Web Report Studio, filters for business views are defined into two categories: predefined filters and user
defined filters. As the name suggests, predefined filters are defined in advance when creating or editing the
business views in JReport Designer, and user defined filters are created on business views while they are used.
Filters can be applied to a business view in the report wizard.
1. In the Bind Data screen of the Web Report Wizard or in the report wizard, select the business view that
you are going to add filters to from the Data Source drop-down list, and then click the Filter button on
the right. The Query Filter dialog is displayed.
2. The dialog has the basic and advanced modes for you to define a filter using either simple expressions or
complex expressions.
When it is in the advanced mode, you can also choose to apply a predefined filter of the specified business
view from the Query Filter drop-down list. If you prefer to define a filter on your own, select User
Defined from the drop-down list, and then define the filter according to your requirements. You can also
edit a predefined filter if required and save it as a user defined filter to the business view.
❍
To define a filter using simple expressions:
a. Make sure the dialog is in the basic mode.
b. Select the field on which the filter will be based from the field drop-down list.
c. From the operator drop-down list, set the operator with which to compose the filter expression.
d. Type the values of how to filter the field in the value text box, or select one or more values from
the drop-down list.
e. If you want to add another condition line, from the logic operator drop-down list,
■
■
To add a condition line of the AND relationship with the current line, select AND, then define the
expression as required.
To add a condition line of the OR relationship with the current line, select OR, then define the
expression as required.
Repeat this to add more filter expressions if required. To delete a condition line, click
❍
on its left.
To define a filter using complex expressions:
a. Switch the dialog to the advanced mode.
b. Click the Add Condition button to add a condition line.
c. From the field drop-down list, select the field on which the filter will be based.
d. From the operator drop-down list, set the operator with which to compose the filter expression.
e. Type the values of how to filter the field in the value text box, or select one or more values from
the drop-down list.
f. To add another condition line, click the Add Condition button and define the expression as
required. Then click the logic button until you get the required logic to specify the relationship
between the two filter expressions. The logic can be AND, OR, AND NOT, or OR NOT.
g. Repeat the above steps to add more filter expressions if necessary.
To group some conditions, select them and click the Group button, then the selected conditions
will be added in one group and work as one line of filter expression. Conditions and groups
together can be further grouped. To take any condition or group in a group out, select it and click
Ungroup. It is the equivalent of adding parenthesis in a logic expression.
To adjust the priority of a condition line or a group, select it and click the Up or Down button.
To delete a condition line or a group, select it and click the Delete button.
3. After you finish the report wizard, the specified filter will be applied to the business view, so that your
report will get data that meets the filter condition only.
Note: Query filters take effect on the component level, which means each time you create a component, you
can apply a filter to the business view the component uses and it will not affect other components based on the
same business view.
Filtering the data components in a report
There are the following ways you can take in order to filter the data components in a web report: using the
Filter dialog, using the Filter panel, using the Filter web control, or via shortcut menu.
Using the Filter dialog
When using the Filter dialog to filter report data, you can only make the filter applied to a specific data
component in the current web report.
To filter report data using the Filter dialog:
1. Click Menu > Edit > Filter, or the Filter button
displayed.
on the Standard toolbar. The Filter dialog is
2. From the Apply to drop-down list, select the component in the web report to which you want to apply the
filter.
3. Define the filter using either simple expressions or complex expressions.
4. When done, click OK to apply the filter.
The Filter dialog provides an entry to all the filters used in the current web report except query filters. You can
click the Inspector button to view the detailed filter information.
Using filter controls
You can also use the Filter web control to filter one or more data components that use the same data source in
a web report. A filter control can do filtering based on one field. For details, see Using filter control to filter
report data.
Using the Filter panel
The Filter panel on the left of Web Report Studio is used to filter data components in the current report that are
using the same business view. To do this:
1. Add group and detail resources into the Filter panel by clicking + on the panel title bar. Each added group/
detail and its values are housed in a separate box. Group and detail objects can be selected from the
business views used by current report.
2. Select the values you would like to filter the report data. The selected values applies a filter condition to
all the data components in the current report that are using the same business view, regardless whether
the data components contain the fields holding those values.
You can make use of the Ctrl or Shift key to do multiple selection.
The value selection applies a filter condition and the logic is as follows:
●
For one value selection:
Selected_Field=Selected_Value
For example, Country=USA
●
For multiple selection:
(Selected_Field1=Selected_Value1 or Selected_Field1=Selected_Value2) and
(Selected_Field2=Selected_Value3 or Selected_Field2=Selected_Value4)...
For example, (Country=USA or Country=China) and (Year=2008 or Year=2009)
The following shows more about working with the Filter panel:
You can use the buttons on the bottom of the Filter panel to deal with the value selection in the panel.
●
●
●
Back
Goes back to the previous value selection status and refreshes the report data accordingly.
Clear
Removes all the value selection histories and all the filter conditions based on the selections, and refreshes
the report data accordingly.
Forward
Goes forward to the next value selection status and refreshes the report data accordingly.
After right-clicking on a group/detail name title bar, these options are available for managing the group/detail
object.
●
Search
Displays the quick search toolbar in the basic mode right above the value list which enables you to search
values in the group/detail object. You can also use the button
on the group/detail name title bar to
launch the appropriate quick search toolbar. For detailed usage about the quick search toolbar, refer to
Select Values dialog.
●
Clear
Cancels the selection of values in the group/detail object. You can also use the button
name title bar to achieve this.
●
●
●
on the group/detail
Clear All
Cancels the selection of all values in all the group and detail objects.
Sort
Sorts the values in the group/detail object in the ascending or descending order.
Delete
Removes the group/detail object from the Filter panel and the filter you created with the object will be
removed from the report too. You can also click X on the group/detail name title bar to remove it.
Notes:
●
●
When there are more than 300 values for an object, JReport will use Big Data Loading logic. In this case, the
Shift Key for multiple selection will not work.
The filters created via the Filter panel cannot be seen when web reports are opened in JReport Designer.
Cascading relationship between filters
The Filter panel can be regarded as a collection of special filter controls which apply to all data components
using the same data source. While common filter controls can choose the data components they apply, still
under the circumstance of using the same data source.
When there are filter controls, including the special ones in the Filter panel, that apply to the same data
components, and when these controls' fields have cascading relationship, the cascading relationship will be
revealed when you select values in the controls.
For example, there is a filter control based on the field Country, a filter control on City, and another on State.
The first two share one table while the third shares nothing with the other two. In this case, Country and City
values will show cascading relationship, but State values will not participate. You select USA in the Country
filter control, the values in the City filter control will change as follows if the control has scrollbar: the cities
belong to USA are displayed in the upper area of the filter control, and the other cities are put in the lower area
and grayed out. For the case that the City filter control has no scrollbar: all the values remain their positions
and the values not belonging to USA are grayed out. In both cases all the values are selectable. But the State
values remain as before, since the selection of them will not affect the data components that the Country and
City filter controls control.
Using the shortcut menu
You can also use filter-related commands on the shortcut menu to filter the data in a table. To do this, point to
any value of the field other than the group by field, by which you want to filter data, then right-click to show
the shortcut menu. You will see the Filter item which provides a submenu containing the following commands:
●
●
Remove Filter
This command is enabled after you have applied filtering on the field. Clicking this item will remove all filters
on this field.
First N
Shows the First N item with which you can filter data to display records that meet the First N condition. You
can select a number from the submenu or enter a positive integer into the text box on the submenu to
specify the First N condition.
For example, if you select 5 from the First N submenu for a certain field, then only the records with the field
value equal to one of the first five field values will be displayed.
●
Last N
Shows the Last N item with which you can filter data to display records that meet the Last N condition. You
can select a number from the submenu or enter a positive integer into the text box on the submenu to
specify the Last N condition.
For example, if you select 5 from the Last N submenu for a certain field, then only the records with the field
value equal to one of the last five field values will be displayed.
●
●
Field values
"Field values" is not the name for a command on the Filter submenu, but represents some items which are
the values of the field you have right-clicked. Selecting any field value listed here will make the table only
display records with the field value equal to the selected one.
More
This command is enabled if the Filter submenu cannot list all field values. When it is enabled, clicking it will
show the Select Values dialog, with which you can search for and select values conveniently with the help of
quick search toolbar.
Using web controls
Web controls are report components designed to be similar to the kinds of controls found on web pages. In Web Report
Studio, these four types of web controls can be applied: parameter control, parameter form control, filter control, and
navigation control.
This section describes each of the web controls and how to use them.
Using parameter control to specify a parameter to a report
A parameter control is a web control that is bound with a parameter used by the current report. By specifying values to
the parameter in a parameter control, you can pass the parameter values to JReport and run the report with the specified
values.
Cascading parameters cannot be used in parameter controls. If you want to do this, use parameter form controls instead.
To insert a parameter control and use it to specify a parameter to a report:
1. Do either of the following:
❍
❍
Click Menu > Insert > Parameter Control, then point to the destination where you want to add the parameter
control and click the mouse button.
Drag Parameter Control from the Components panel to the destination in the report.
The Insert Parameter Control dialog is displayed.
2. Select the parameter you would like to add to the parameter control, then click OK.
3. A parameter control will be added into the report. Specify the value for the parameter. You may specify the value in
one of these ways.
4. Once the value in the parameter control changes, the report will rerun with the new parameter value.
Note: If the specified parameter is no longer used in the report, the parameter control will become invalid.
Using parameter form control to run reports
A parameter form control is a web control that is bound with the parameters used by the current report or other reports.
By specifying values to the parameters in a parameter form control, you can make the reports run with the specified
parameter values.
To insert a parameter form control and use it to run reports:
1. Do either of the following:
❍
❍
Click Menu > Insert > Parameter Form Control, then point to the destination where you want to add the
parameter form control and click the mouse button.
Drag Parameter Form Control from the Components panel to the destination in the report.
The Insert Parameter Form Control dialog is displayed.
2. Specify the target reports to run using the parameter form control.
❍
❍
To run the current report, select Current Report, then specify the parameters used to run the report from the
Select Parameters box.
To run other reports, select Others, then select the reports you want to run. If all the selected reports contain no
parameters, you cannot finish the dialog.
3. Specify whether to include the Submit button in the parameter form control. If Submit is included, it is used to
submit the parameter values you specified in the parameter form control. If Submit is not included, once you
change the values of a parameter in the parameter form control, the new values will be applied automatically.
4. Click OK in the dialog to save the changes.
The parameter form control is now inserted in the report. It lists the selected parameters for the current report or
lists all parameters used by the specified reports.
5. In the parameter form control, specify values of the listed parameters. You may specify the values in these ways.
6. Click the Submit button to run the current report or the specified reports if the button is available. If there is no
Submit button, the change of values in the parameter form control will trigger report rerunning.
Note: If you save or publish a report containing a parameter form control to another directory, the reports that you bind
the parameter form control with will not be saved or published along with the report.
Using filter control to filter report data
A filter control is used to filter one or more data components in a report, which refer to tables, charts, and crosstabs. For
how a filter control works, see Filtering scenarios.
To insert a filter control and use it to filter report data:
1. Do either of the following:
❍
❍
Click Menu > Insert > Filter Control, then point to the destination where you want to add the filter control and
click the mouse button.
Drag Filter Control from the Components panel to the destination in the report.
The Insert Filter Control dialog is displayed.
2. From the resource list, select the fields of the same data type to bind to the filter control.
To filter components created from the same data source, select a field in the data source.
To filter components created from different data sources, find a common field these data sources contain, then
select the field in each of the data sources.
3. The Apply To drop-down list provides the components involving the selected fields. Select the components which
you want to filter.
4. When done, click OK.
The filter control is inserted in the report. It lists all values of the specified fields. You can select one or more values
to apply.
After inserting filter controls in the report, you can also insert a navigation control for undoing/redoing the value selection
in the filter controls. For details about the usage of navigation control, see Using navigation control to undo/redo value
selection in filter controls.
Managing a filter control
After right-clicking on a filter control, these options are available for managing the filter control.
●
Search
Displays the quick search toolbar in the basic mode right above the value list which enables you to search values in the
filter control. You can also click the Search button
on the title bar of the filter control and then select a sub item to
launch the appropriate quick search toolbar. For detailed usage about the quick search toolbar, refer to Select Values
dialog.
●
Clear
Cancels the selection of values in the filter control. You can also use the button
selection. This operation can be undone/redone.
●
●
●
●
on the title bar to cancel the
Sort
Sorts the values in the filter control in the ascending or descending order.
Hide
Hides the filter control.
Delete
Removes the filter control from the report and the filter you created with the filter control will be removed from the
report too. You can also use the button X on the title bar to delete the filter control.
Properties
Opens the Filter Control Properties dialog for editing the properties of the filter control.
Cascading relationship between filter controls
When there are filter controls that apply to the same data components, and when these controls' fields have cascading
relationship, the cascading relationship will be revealed when you select values in the controls.
For example, there is a filter control based on the field Country, a filter control on City, and another on State. The first
two share one table while the third shares nothing with the other two. In this case, Country and City values will show
cascading relationship, but State values will not participate. You select USA in the Country filter control, the values in the
City filter control will change as follows if the control has scrollbar: the cities belong to USA are displayed in the upper
area of the filter control, and the other cities are put in the lower area and grayed out. For the case that the City filter
control has no scrollbar: all the values remain their positions and the values not belonging to USA are grayed out. In both
cases all the values are selectable. But the State values remain as before, since the selection of them will not affect the
data components that the Country and City filter controls control.
Notes:
●
●
When there are more than 300 values in a filter control, JReport will use Big Data Loading logic. In this case, the Shift
Key for multiple selection will not work.
Sometimes, when the position of a filter control is changed due to layout change, the advanced search toolbar in the
filter control may not follow the filter control but stay where it is.
Using navigation control to undo/redo value selection in filter controls
A navigation control can be considered as an accessorial control for filter controls and used to deal with the value
selection operations in all the filter controls in the same report.
To insert a navigation control into a report, do either of the following:
●
●
Click Menu > Insert > Navigation Control, then point to the destination where you want to add the navigation
control and click the mouse button.
Drag Navigation Control from the Components panel to the destination in the report.
A navigation control is a combination of three buttons:
●
●
●
Back
Goes back to the previous value selection status and refreshes the report data accordingly.
Clear
Removes all the value selection histories and all the filter conditions based on the selections, and refreshes the report
data accordingly.
Forward
Goes forward to the next value selection status and refreshes the report data accordingly.
Adding conditional formats to fields
You can add some conditional formats to a field in tables or crosstabs, which refer to the DBField,
parameter field, formula field, and summary field, then when the specified condition is fulfilled, the
defined format will be applied to the field values for highlighting.
To add conditional formats to a field:
1. Right-click the field and select Conditional Formatting from the shortcut menu to access the
Conditional Formatting dialog.
2. Click the button
to open the Edit Conditions dialog to define a condition using either simple
expressions or complex expressions according to your requirements.
The newly added condition will then be displayed and highlighted in the Condition box in the
Conditional Formatting dialog.
3. In the Format box, set the format which will be applied to values of the field when the specified
condition is fulfilled, for example, the font face, font size, font color, etc.
4. Repeat the above steps to add more conditions and define the format for each condition.
To edit a condition, select the condition in the Condition box, then click
dialog, edit the expressions as required.
. In the Edit Conditions
To remove a condition and the corresponding format, select the condition in the Condition box and
click
.
To adjust the priority of a condition, select the condition in the Condition box and then click
.
5. Click OK to apply the conditional formats to the field.
See also Conditional Formatting dialog and Edit Conditions dialog for details about options in the
dialogs.
or
Applying parameters
When running a web report with parameters, a dialog is displayed for you to specify parameter values.
After the report is opened in Web Report Studio, you can change the parameter values using the
following ways.
Using the Parameters panel
The Parameters panel is available when the current web report uses parameters. It lists all the
parameters used by the report with your last-time saved default values, which could be the values
saved in this panel last time, or in the Enter Parameter Values dialog or Parameter Settings dialog, or
when advanced running or scheduling the report. If you have not yet set the default values on the
server, or if you did but your last-time saved default values cannot fully match the current parameters,
all the parameters will use their default values specified in the parameters' definition as the initial
values.
Edit the values according to your requirement and then click Apply to make the report run with the
specified parameter values. You may specify parameter values in these ways.
If you want to save the current specified parameter values as the default values for the report, select
Save as default in the panel (to make this option available, you need to make sure the Enable Setting
Default Parameter Values For Web Report is selected in the Profile > Customize Server Preferences >
Advanced tab).
If you would like the report to run on the console with the saved default values directly next time,
without popping the Enter Parameter Values dialog, unselect Re-enable Parameter Screen, which is
available when the option Enable Hiding Initial Parameter Dialog For Web Report is checked in the
Profile > Customize Server Preferences > Advanced tab. Note that if later the last-time saved default
values cannot completely match the report parameters, the parameter dialog will still be displayed. You
can check this option to show the Enter Parameter Values dialog again after it has been hidden.
The above two options are user-report level settings, that is to say, they take effect when both the
same user and report are matched. This also applies to admin users, and therefore admin cannot
customize the settings for all users.
If you want to reset the parameter values, use the Reset button, which varies on different situations:
●
When Save as default is available in the panel, the Reset button contains a text part and a triangle
icon. You can choose to reset the values to either of the following by clicking the triangle. If you click
the text part of the button directly, the values will be reset to the original default values.
❍
❍
●
Original Default Values
The default values defined in the parameters' definition.
User Defined Default Values
Your last-time saved default values.
When Save as default is unavailable in the panel, the Reset button contains only the text part.
Clicking it will reset the values to the original default values.
Using parameter controls
You can insert a parameter control and bind it with a parameter used by the current report. By
specifying values to the parameter in the parameter control, you can pass the parameter values to
JReport and run the report with the specified values. For details, see Using parameter control to specify
a parameter to a report.
Using parameter form controls
You can insert a parameter form control, make it run the current report, bind it with one or more
parameters used by the report. By specifying values to the parameters in the parameter form control,
you can make the report run with the specified parameter values. For details, see Using parameter
form control to run reports.
Sorting report data
You can sort the records or groups at a certain group level in a table, crosstab or chart.
●
●
Sorting records: Changing the order of records in the whole table, crosstab or chart, or in each
group if there are.
Sorting groups at a group level: Changing the order of groups at the specified group level, that
is, the groups will be sorted by value of the group field.
To sort data on a certain field using shortcut menu:
1. Point to any value of a detail field or group field by which to sort the data in a table, crosstab or
chart, and then right-click.
2. Choose the command Sort > Ascend or Sort > Descend from the shortcut menu.
If what you right-click in Step 1 is a detail field value, the sorting will affect the order of detail
records in the table, crosstab or chart; if it is a group field value, the order of groups in the group
level represented by the group field will be rearranged.
To remove the sort condition on a field, click Sort > No Sort from the shortcut menu.
Note: If you use the shortcut menu to sort the report data by a field and then sort by another field, the
later sort condition will replace the former one.
Applying CSS styles
CSS styles can be applied to web reports formatting their appearance and characteristics. You can
create and set up your own CSS styles in JReport Designer or any other CSS editor. When you publish
your catalogs to JReport Server, you can include these custom styles with the catalogs.
Styles can be applied to a table, crosstab, or chart individually, or to multiple components or the whole
report at a time. The last style always takes effect when more than one style is applied to the same
object.
Applying a style to a report
When a style is applied to the whole report, all components in the report will take a uniform
appearance. You can apply a style in one of the following ways:
●
●
Specify a style in the Style page of the Web Report Wizard.
In Web Report Studio, click the blank area outside of the report field, then select a style from the
Report Style list on the Edit menu.
Applying a style to a component
You can apply a style to a table, crosstab, or chart by selecting the component in Web Report Studio
and then doing one of the following:
●
Select a style from the Report Style list on the Edit menu.
●
Right-click and then select a style from the Apply Style list on the shortcut menu.
Applying a style to multiple components
You can apply a style to multiple tables, crosstabs, and charts by selecting the components and then
selecting a style from the Report Style list on the Edit menu.
Saving the report
To save the changes you made to the current report, click Menu > File > Save (or the Save button
Standard toolbar).
on the
If the report is newly created and has not yet been saved, the Save As dialog will be displayed.
1. In the Save in section, browse to the folder where you want to save the web report in the server resource tree.
The folder may be Public Reports or My Reports. You can use the
button to return to the parent folder.
The resource table shows the resources in the current directory. Click the column names to change the order of
the report in the table list if required.
2. In the File Name box, enter the name of the report or use the default name. The default file type is web report.
3. Click the Advanced button to set the advanced settings for the report if required.
a. From the Status drop-down list, specify a status for the report.
b. The catalog that the report uses is shown.
Specify the relationship between the saved report and the catalog used to run it:
■
■
Set Original Catalog as Linked Catalog into Saved Report
If checked, the saved report will be linked with the catalog and will run with the catalog no matter
whether the two are in the same directory. If later the catalog is updated, the saved report will run with
the latest version of the catalog.
Set Catalog Copy to Target Folder
If checked, the catalog will be copied to the directory where the report is saved and the saved report will
run with the copied catalog.
c. Optionally, input comments in the Description box as a description for the report.
4. Click Save to save the report.
To save a copy of a report, click Menu > File > Save As (or the Save As button
show the Save As dialog, and then do as above.
on the Standard toolbar) to
To find a newly saved web report version, browse to select the row that the web report is in on the JReport Console >
Resources page, click Tools > Version on the task bar, and then click the Web Report Versions tab.
Note: You will not be able to save the report to some locations if you do not have the required permissions. You need
to have Write access to the directory.
Exporting/Printing the report result
When you finish editing a web report, you may want to export it to other formats or have it printed.
Exporting the report result
You can export the report result as a result version or as a local file in these formats: HTML, PDF, Text, Excel,
RTF, XML, and PostScript.
1. Click Menu > File > Export (or the Export button
dialog.
on the Standard toolbar) to display the Export
2. In the File Name field, specify the name of the exported result file.
3. Specify the destination of the result:
❍
❍
❍
View Report Result: The result will be directly opened in the web browser if the format is supported by
a plug-in of the web browser; otherwise it will prompt you to save the result file.
Save to File System: The web browser will prompt you to save the result file to a specified folder. If
selected, you need to provide a name for the result file in the File Name field.
Save to Version System: The result will be saved as a result version in JReport Server's versioning
system.
4. From the Select Format drop-down list, select the format in which to export the result.
5. Expand More Options to set the options for the selected format. For details about settings of each format,
see Export dialog.
6. Click OK to confirm.
Printing the report result
You can print the report result to a PDF/HTML file.
To print the result of a web report:
1. Click Menu > File > Print (or the Print button
on the Standard toolbar) to display the Print dialog.
2. In the General tab, specify the printer properties, the page range and copies you want to print.
3. In the Appearance tab, specify the appearance of the printed report as required.
4. Click OK. The PDF/HTML result file will be opened in an associated program with which you can print the
result to a printer.
See also Print dialog for additional information about options in the dialog.
JDashboard
JDashboard is a new way of information delivery, using a user portal user interface rather than a web
report or page report. Users can create, edit and browse dashboards from the JReport Console using
JDashboard. Library components are the basic members in dashboards for presenting data via intuitive
components such as charts, crosstabs, tables, and geographic maps. Library components are created
using JReport Designer (for details, see Library Components in the JReport Designer User's Guide), and
then published to the component library on JReport Server for use when creating or modifying
dashboards. With pre-built library components, users can freely choose the objects they want to
display in the dashboard, without having to know how these objects were created, what data sources
to use, what styles to set, etc. A dashboard can hold multiple library components so that when
browsing the dashboard users are able to see multiple data aspects. Within a dashboard, library
components are able to communicate with each other via the message mechanism. This allows actions
such as common filters to be applied to all the components of a dashboard even when coming from
different data sources.
Since predefined containers are used for holding objects, it is easy to move objects around and resize
them in dashboards.
This chapter covers the following topics:
●
JDashboard basic concepts
●
JDashboard window elements
●
Creating dashboards
●
Inserting components
●
General operations in JDashboard
●
Manipulating data components
●
Filtering component data
●
Specifying parameter values
●
Saving dashboards
●
Exporting library components
●
Printing library components
●
Setting JDashboard as the server home page
●
Running dashboards via URL
●
Running and editing reports in JDashboard
●
Opening Visual Analysis in JDashboard
Note: A JDashboard license is required in order to use JDashboard and all the related features. If you
do not have a JDashboard license please contact your Jinfonet Software account manager to obtain a
license. In addition, JDashboard cannot run on Internet Explorer 8.
JDashboard basic concepts
The following shows the main JDashboard concepts:
Library components
Library components are used to build dashboards. They are able to present data via intuitive
components such as charts, crosstabs, tables, and geographic maps. Library components can be
created and edited using JReport Designer, and then published to JReport Server for use in
dashboards. Library components can also come from report components. JReport Designer provides a
way to save a data component in a web report to a library component. Or when a dashboard user
inserts a web report component into a dashboard, the report component will be converted to a library
component and the user can save the library component. Library components use .lc as the file suffix.
Component library
Component library contains one Public Components folder and a My Components folder for each specific
dashboard user.
Public Components and My Components are two built-in folders in the server resource tree root for
storing library components. The Public Components folder contains public components available to
everyone. The My Components folder holds personal components for each dashboard user.
Dashboard
A workspace window that can contain any number of library components.
●
●
●
Components from library
When inserting a library component from the component library into a dashboard, you are not
copying the component from the library, but instead referencing it from the library, in this sense, the
changes to the component in the library will be reflected in all of the dashboards referencing the
component. The contents of library references in dashboards cannot be edited since they are
referenced resources.
Report components
Data components such as tables, charts, crosstabs, and geographic maps in reports can be inserted
into dashboards as library components.
Objects from the Toolbox
In addition to library components users can select objects from the Toolbox such as labels, images,
special fields, sliders, filter controls, third-party objects, and HTML components.
Message
The information that one library component can send to another. The sending and receiving of
messages between library components are defined in JReport Designer.
JDashboard window elements
JDashboard is opened in a web browser. The full-featured JDashboard window is composed of three
sections: the dashboard title bar at the top, the side bar on the left providing options for working with
dashboards, and the dashboard editing area where you navigate and modify dashboards. Since
JDashboard can also be used to access Visual Analysis, if your JReport Server is enabled with Visual
Analysis, the elements on the JDashboard window have slight differences.
The ways of accessing JDashboard
Here are two ways of accessing the JDashboard:
By creating a new dashboard
On the JReport Console > Resources page, click New > Dashboard. The JDashboard window will be
launched with a blank dashboard. This way enters the edit mode.
By running an existing dashboard
On the JReport Console > Resources page, browse to the target dashboard and choose the appropriate
way to enter the desired view or edit mode.
View mode and edit mode
JDashboard has two working modes: the edit mode presents full functionalities and the view mode just
serves for viewing purpose without any editing abilities. After JDashboard is open, you cannot switch
one mode to another. If you need to do this, reopen JDashboard using the appropriate way.
To enter the view mode:
●
Browse to locate an existing dashboard on the JReport Console page, then click the Run button
on the floating toolbar, or click Run > Run on the standard toolbar.
To enter the edit mode:
●
●
On the JReport Console page, click New > Dashboard.
Browse to locate an existing dashboard on the JReport Console page, then click the Edit button
on the floating toolbar, or click Run > Edit on the standard toolbar.
You can also directly click the name of a dashboard to enter the view mode if the dashboard is in the
My Reports folder, or either of the two modes if it is in the Public Reports folder, depending on the
permission you are granted on the dashboard:
●
●
When you have the Execute permission on the dashboard, you will be directed to the view mode.
When you have the Edit permission on the dashboard but do not have the Execute permission, you
will enter the edit mode.
●
When you have both the Execute and Edit permissions on the dashboard, you will enter the view
mode.
The following introduces the full UI elements based on the edit mode.
Dashboard title bar
The dashboard title bar at the top contains tabs labeling the names of the open dashboards.
Dashboard name tabs
Each tab represents an open dashboard and the dashboard name is shown on the tab.
The following are operations on the tabs:
●
●
Click a tab to activate the corresponding dashboard.
Rename a tab. Double-click a tab name to enter the editing mode. After typing a new name, press
Enter or click outside of the input field to save the name.
●
Move a tab. Drag a tab and drop it beside a different tab so as to change the tab order.
●
Click x beside a dashboard name to close the dashboard.
Adds a new blank dashboard in the current web browser.
If Visual Analysis is enabled, you can leave the cursor on the button for one second and a drop-down
menu will be displayed containing the following options:
●
●
New Dashboard
Creates a new blank dashboard as a new tab.
New Analysis
Opens Visual Analysis as a new tab.
Specifies the language in which the dashboard will be displayed. Available only when Enable NLS is
checked in the Profile > Customize Server Preferences > Advanced panel on the JReport Console page.
Dashboard editing area
Dashboard view has header and body.
The dashboard header can contain labels, images, and special fields.
The dashboard body can contain report components, library components, filtering tools, third-party
objects, and HTML components. You can insert the same library component repeatedly to the same
dashboard body.
Library components inserted to dashboards are references of the library component in component
library. The changes to a library component in the library will be reflected in all of the dashboards
referencing the library component, such as removal of library components, version updated, permission
changed.
Side bar
The options available on the side bar are determined by the feature profile that is selected as the
default profile in the Profile > Configure Profile > JDashboard > Features tab and the property setting
on the Profile > Configure Profile > JDashboard > Properties tab (profile has the higher priority). The
default JDashboard profile provides full options.
The side bar on the left contains these buttons:
Shows or hides the Resources panel which includes these branches:
●
●
●
Component Library lists the library components created in and published from JReport Designer.
You can select a library component and drag it into the dashboard body.
Reports lists page reports and web reports. You can open a report from JDashboard or add report
data components into your dashboards.
Toolbox lists the objects that can be inserted in your dashboards such as labels, images, special
fields, filtering tools, third-party objects, and HTML components.
You can use the quick search toolbar at the top of the panel to search for any desired resources in a
fast and convenient way (to display the toolbar, click the Search button
of the panel).
at the upper right corner
New
Creates a new blank dashboard with a new tab added.
If Visual Analysis is enabled, clicking the button will bring out a drop-down menu that contains the
following options:
●
●
New Dashboard
Creates a new blank dashboard as a new tab.
New Analysis
Opens Visual Analysis as a new tab.
Open
Displays the Open Dashboard dialog for you to specify a dashboard to open, or the Open Document
dialog where you can select a dashboard or a visual analysis template to open. Which dialog will be
displayed depends on whether Visual Analysis is enabled.
Save
Saves the changes made to the current dashboard.
Refresh
Refreshes the current dashboard.
Enter Parameter Values
Opens the Enter Parameter Values dialog which lists all the parameters used in the dashboard for
specifying their values.
Clear Filters
Removes all the filters from the current dashboard including those generated via sliders, filter controls,
messages, drilling and going actions and those designed using web browsers such as Page Report
Studio and Web Report Studio, except query filters and others designed and taking effect in JReport
Designer.
Arrange
Automatically arranges the library components in the current dashboard to be tidy. It is an instant
action.
Export
Displays the Export dialog for exporting library components in the current dashboard.
Print
Displays the Print dialog for printing library components in the current dashboard.
Options
Displays the following options:
●
New
Creates a new blank dashboard.
If Visual Analysis is enabled, the New option contains a submenu:
❍
❍
●
●
●
●
●
●
Dashboard
Creates a new blank dashboard as a new tab.
Analysis
Opens Visual Analysis as a new tab.
Open
Displays the Open Dashboard dialog for you to specify a dashboard to open, or the Open Document
dialog where you can select a dashboard or a visual analysis template to open. Which dialog will be
displayed depends on whether Visual Analysis is enabled.
Save
Saves the changes made to the current dashboard.
Save As
Saves the dashboard with a different name or to a new location.
Export
Displays the Export dialog for exporting library components in the current dashboard.
Print
Displays the Print dialog for printing library components in the current dashboard.
Clear Filters
Removes all the filters from the current dashboard including those generated via sliders, filter
controls, messages, drilling and going actions and those designed using web browsers such as Page
Report Studio and Web Report Studio, except query filters and others designed and taking effect in
JReport Designer.
●
●
●
●
●
●
●
●
●
●
Share Parameter
Opens the Share Parameters Setting dialog for sharing parameters between library components.
Arrange
Automatically arranges the library components in the current dashboard to be tidy. It is an instant
action.
Auto Arrange
Automatically arranges the library components in the current dashboard to be tidy once the layout
requires arrangement. It is a status setting. After selecting it, this option will be kept checked and
the Arrange option will be disabled until you unselect Auto Arrange. The status will be saved with the
dashboard.
Set as Server Home
Sets the current JDashboard status as the home page after logging onto JReport Server. For details,
see Setting JDashboard as the server home page.
Language
Allows you to specify the language in which the dashboard will be displayed. Available only when
Enable NLS is checked in the Profile > Customize Server Preferences > Advanced panel on the
JReport Console page.
Component Title Bar
Customizes the way of showing component title bar and the icons on it.
Themes
Opens the Themes dialog for selecting a theme to apply to the current dashboard.
Show/Hide Dashboard Header
Changes the current status of the dashboard header from being shown to hidden or from being
hidden to shown.
Help
Displays the JDashboard help documents.
Exit
Exits JDashboard.
Creating dashboards
To create a dashboard:
1. On the JReport Console > Resources page, click New > Dashboard. A blank dashboard will be created.
2. The upper section with the text "Dashboard Title" of the editing area is the dashboard header, where you
can insert labels, images, and special fields. The dashboard body is the section below the header. In the
body you can insert report components, library components, filtering tools, third-party objects, and HTML
components. For details see Inserting components.
3. When the mouse hovers on the header section, the header is outlined and you will see the border between
the header and the body. You can resize the two sections by dragging the border line. The arrow button
that appears at the bottom right of the header is used to hide the header.
After you have entered JDashboard, if you want to create more dashboards in the same web browser, see here.
Inserting components
You can insert library components and report data components as well as labels, images, special fields,
filtering tools, third-party objects, and HTML components into dashboards via the Resources panel. To
access the panel, click Show Resources
on the side bar.
The following shows inserting a specific component in detail.
Inserting library component references
When inserting a library component from component library into a dashboard, you are not copying the
component from the library, but instead referencing it from the library, in this sense, the changes to the
component in the library will be reflected in all of the dashboards referencing the component. The contents
of library references in dashboards cannot be edited since they are referenced resources.
To reference a library component into the dashboard body:
1. Click Show Resources
on the side bar to display the Resources panel.
2. Expand the Component Library node, browse to find the library component you want to insert, then
drag it to the destination in the dashboard body.
Inserting report data components
Data components such as tables, crosstabs, charts, and geographic maps in existing page reports or web
reports can be directly inserted into dashboards after being converted into library components
automatically.
Since both library components and web reports use business views as data sources, all data components in
web reports can be converted to library components successfully.
However, page reports use queries or report cubes or business cubes as data sources other than business
views, and business cubes are built on tables while report cubes and business views are created on top of
the same queries, therefore, only when data components in page reports use queries or report cubes as
data sources and the queries or report cubes have corresponding business views, can the components be
converted to library components and used in dashboards. So if you would like your page report
components to be added in dashboards, you need to make sure the components are created on queries or
report cubes and a business view is created for each of the report cubes.
Currently library components do not support some features of page report components, after the latter are
inserted into dashboards, those features will be removed. This may result in that the data components in
dashboards looks different from they are in page reports. For features that are not supported in
JDashboard, they will either be ignored, removed, or applied with the default values.
The following table lists how JDashboard deals with the unsupported page report features:
In Page Report Components
In Library Components
Display types like Barcode, Check box, etc
Ignored
Special fields
Removed
Dynamic resources
Changed to constant resources
Master/Detail reports
Ignored
Subreports
Removed
Nested data components that is one contains
another
The ownership is removed and the involved data
components are regarded as individual components.
Definition properties
Ignored
Formula-controlled properties
Default values are applied.
Other components
Removed
To insert a report data component into the dashboard body:
1. Click Show Resources
on the side bar to display the Resources panel.
2. From the Reports node, expand the report that contains the wanted data component and drag the
component into the dashboard body.
3. If the report component uses parameters, the default values will be applied. To change the parameter
on its title bar and select Edit Setting from the dropvalues, after the component is loaded, click
down list to display the configuration panel. Change the parameter values in the panel and then click
OK to apply the new values.
The inserted report data component runs with the report's catalog. It will not be able to run if the catalog
is removed or updated. The report component does not synchronize with the other library components in
the dashboard via messages and not controlled by the runtime sliders or filters.
After a report data component is inserted in a dashboard, you can save it as a library component. To do
this:
1. On the title bar of the inserted report data component, click
down list.
and select Save As from the drop-
2. In the Save As dialog, specify a location to save the component and a name for the component, then
click OK.
Inserting a label
Labels can be inserted in the dashboard header. To do this, click Show Resources
on the side bar to
display the Resources panel, then from the Toolbox node, drag Label to the destination in the dashboard
header, then double-click the label and edit the text as required.
Inserting a dashboard title
A dashboard title is a special label. It can be inserted in the dashboard header. To do this, click Show
on the side bar to display the Resources panel, then from the Toolbox node, drag
Resources
Dashboard Title to the destination in the dashboard header, then double-click the title and edit the text
as required.
Inserting an image
Images can be inserted in the dashboard header.
1. Click Show Resources
on the side bar to display the Resources panel.
2. From the Toolbox node, drag Image to the destination in the dashboard header. The Insert Image
dialog is displayed.
3. Specify the image you want to insert.
❍
❍
❍
To use an image in the local file system, select Local File, then click Browse to find the image.
To use an image on a website, select Web URL, then input the image URL or paste the URL in the
File URL text field.
To use an image in the image library of JDashboard, select Library, then select the image in the My
Pictures box.
4. Click OK to insert the image.
Inserting a special field
You can insert these types of special fields in the dashboard header:
●
●
●
●
●
User Name
The user name with which you log onto JReport Server.
Modified Date
The date when the dashboard was last modified.
Modified Time
The time when the dashboard was last modified.
Print Date
The date to run the dashboard.
Print Time
The time to run the dashboard.
To do this:
1. Click Show Resources
on the side bar to display the Resources panel.
2. From the Toolbox node, drag Special Field to the destination in the dashboard header. The Insert
Special Field dialog is displayed.
3. Choose the desired special field and click OK to insert it into the header.
Inserting a slider
Sliders can be inserted in the dashboard body. They are used to filter component data. For details, see
Using sliders.
Inserting a filter control
Filter controls can be inserted in the dashboard body. They are used to filter component data. For details,
see Using filter controls.
Inserting a third party gadget via URL
A web page can be inserted in dashboards. All you need to do is give its URL. Note that some web sites
such as http://www.google.com do not allow Gadgets to load them.
1. Click Show Resources
on the side bar to display the Resources panel.
2. From the Toolbox node, drag URL Frame into the dashboard body. The Insert URL Frame dialog is
displayed.
3. In the Title text field, give a title for the window that will display the contents of the web page.
4. In the URL text box, type in the URL of the web page. If needed, click the Add Parameter button to
insert a parameter to the URL to compose a dynamic URL (if no data source is specified, the Select
Data Source dialog will be dispalyed for you to select the data source that contains the parameter you
want firstly).
You should provide a complete URL address. A URL without "http://", for example www.jinfonet.com,
will not be automatically added "http://" since it is regarded a relative path, which may lead to that
the URL cannot be opened in some browsers.
5. If you would like the specified web page to refresh periodically, select Auto refresh, then specify the
interval to refresh.
6. Click OK. The specified web page will be inserted into the dashboard. You can then view the web page
from JDashboard. If parameters are used in the URL, you can click
on the side bar to specify the
parameter values as you want, then you can get different web pages based on different parameter
values.
See the Insert URL Frame dialog for details about the options in the dialog.
Inserting an HTML component
An HTML component allows for typing text, comments, and messages using a simple-featured text editor.
It can be inserted in the dashboard body.
1. Click Show Resources
on the side bar to display the Resources panel.
2. From the Toolbox node, drag HTML to the destination in the dashboard body. The Insert HTML dialog
is displayed.
3. Specify a title for the HTML component.
4. In the text box, type text directly. You can make use of the buttons above the text box to format the
text such as font face, size, style, color, and alignment, insert images, and create hyperlinks.
5. Click OK to insert the HTML component.
See the Insert HTML dialog for details about the options in the dialog.
General operations in JDashboard
This section provides a general view of the operations you can perform in JDashboard.
Operations on dashboards
●
Creating a new blank dashboard in the current web browser
The ways to create a dashboard differ depending on whether your JReport Server is enabled with
Visual Analysis.
❍
❍
When Visual Analysis is disabled, choose a method from the following:
■
Click + beside the rightmost tab on the dashboard title bar.
■
Click the New button
■
Click the Options button
on the side bar.
on the side bar and select New from the option list.
When Visual Analysis is enabled, choose a method from the following:
■
■
Click + beside the rightmost tab on the dashboard title bar.
On the dashboard title bar, leave the mouse cursor on the + button beside the rightmost tab for
one second until a drop-down menu displays, then select New Dashboard from the menu.
■
On the side bar, click the New button
■
On the side bar, click the Options button
and then select New Dashboard.
and then select New >Dashboard.
A blank dashboard will be created in the browser. You can then add components to customize the
dashboard.
●
Opening another dashboard in the current web browser
on the side bar, or click the Options button
and then select Open
Click the Open button
from the option list. In the displayed dialog, browse to the desired folder, select the dashboard you
want to open and then click OK, or simply double-click the dashboard to open it.
●
Showing, hiding and resizing the dashboard header
To show or hide the dashboard header, click the Options button
Show/Hide Dashboard Header from the option list.
on the side bar and select
Even though the dashboard header is open, its border is unseen by default. However, when you drag
objects into the dashboard editing area, you will see the area is divided into two sections with the
activated section highlighted in grey: the upper section is the header and the lower the body. Or you
can simply press Ctrl on the keyboard to make the border between the header and body shown.
Then drag the border line vertically to adjust the size of the header and body.
●
Removing all filters from a dashboard
JDashboard provides the ability to remove all the filters from the current dashboard at a time
including those generated via sliders, filter controls, messages, drilling and going actions and those
designed using web browsers such as Page Report Studio and Web Report Studio, except query
filters and others designed and taking effect in JReport Designer. To do this, click the Clear Filters
button
on the side bar, or click the Options button
option list.
●
Refreshing the current dashboard
Click the Refresh button
●
and then select Clear Filters from the
on the side bar to refresh the data of the current dashboard.
Applying a theme to the current dashboard
on the side bar and select Themes from the option list. In the Themes
Click the Options button
dialog, select a theme from the left panel and then click OK.
●
●
Closing a dashboard
For the current dashboard, click X on its name tab to close it. For the other open dashboards, hover
the cursor on a name tab until X appears, then click X to close that dashboard.
Exiting JDashboard
on the side
If you want to exit JDashboard and release the resources, click the Options button
bar and select Exit from the option list. Do not use the close button on the browser window as that
may not release the resources used by JDashboard.
●
Asking for help
on the side bar and select Help from the option
At any time, you can click the Options button
list to access the JDashboard help documents. Furthermore, you can click
in any dialog to show
the help document about the dialog.
Operations on objects in the dashboard header
●
Editing an object
Hover the cursor on the object and then click
that appears around the object. A dialog will be
displayed for you to edit the object. For a label or the dashboard title, you can edit the text related
properties like font face, font color, etc. For a special field, you can change it to another special field
and edit the text related properties. For an image, you can select another image to replace the
current one.
●
●
●
Moving an object
Place the cursor on the object until it becomes a four-arrow icon, then drag to the desired position.
Resizing an object
Place the cursor on the object until an orange rectangle appears, next move the cursor on the right
border, bottom border, or the bottom right corner until the cursor becomes a two-arrow icon, then
drag to the desired position.
Deleting an object
Hover the cursor on the object and then click
that appears around the object.
Operations on components in the dashboard body
●
●
Moving a component
Place the cursor on the component title bar until it becomes a four-arrow icon, then drag to the
desired position.
Resizing a component
Place the cursor on the component's right border, bottom border, or the bottom right corner until the
cursor becomes a two-arrow icon, then drag to the desired position.
Editing a component
●
on the component title bar and select Edit Setting from the drop-down list. In the
Click
corresponding edit dialog, edit the setting as required.
●
●
●
Navigating component data via scroll bar
For tables, crosstabs and charts, you can use the scroll bar to navigate their data if the container
cannot display all data of the component.
Turning component pages
If a table or a crosstab contains more than one page, a page navigation bar specific for the
component will be available right below the component. You can use the navigation bar to view the
desired pages:
❍
Click a number to go to that page.
❍
Input a number in the text field.
❍
Click Prev to go to the previous page.
❍
Click Next to go to the next page.
Customizing the auto refresh action
For a library component that uses only one business view as the data source, if its Auto Refresh
on the component title bar and select Refresh from the option list
feature is enabled, you can click
to adjust the refresh interval or pause the auto refresh action with the Refresh Interval dialog.
❍
●
To change the refresh interval, click the drop-down list to select the new interval. Currently there
are only 3 values available, which are ordinal multiples (starting from 2) of the default interval
value defined in JReport Designer.
❍
To make the auto refresh action paused, click
.
❍
To resume the auto refresh action after it is stopped, click
.
Going to links
Once an object in a library component has been linked to a report, a web page, or an e-mail address,
you will find the mouse cursor changes into a hand icon when hovering on the object, you can then
click the object to launch the linked target.
Note: If the trigger object of a link in a library component happens to be in some hierarchies
(which means you can also perform the go-down action on the object by single click), you can
click the trigger object to directly open the link in JDashboard only when the click priority of the
link action is specified to be the highest for the library component at design time. If the priority
of the go-down action is specified the highest, you can click the trigger object to open the link
only when you have reached the lowest level of the hierarchies by going down on the object first.
●
Sending messages
If an object in a library component has been defined to send a message, by triggering the event
defined for sending the message, the message will be sent out and the components defined for
receiving the message will do things as defined.
The sending and receiving of messages is defined in JReport Designer, see Delivering messages
between library components in the JReport Designer User's Guide.
●
Maximizing a component
on the component title bar and the component will take up the whole dashboard body. By
Click
clicking the button again the component will be restored to the original size.
●
Customizing the way of showing the component title bar and options on it
on the side bar and select Component Title Bar from the option list.
Click the Options button
In the Customize Component Title Bar dialog, specify the way of showing the component title bar and
the options on it, and then click OK.
●
Deleting a component
Click
●
on the component title bar and select Delete from the drop-down list.
Making use of the configuration panel
Each library component can be equipped with a configuration panel. The configuration panel can be
used to specify parameter values to its library component, to filter or sort the data of its library
component, or to change properties of objects in its library component. For how a configuration panel
is configured, see Using the configuration panel in the JReport Designer User's Guide.
Once a configuration panel has been defined for a library component, you can open it in JDashboard
and then perform actions as defined. To do this, on the title bar of the library component, click
and select Edit Setting from the drop-down list to display the configuration panel. After specifying
values in the panel, click OK to apply the values in the library component. The Cancel button is used
to close the configuration panel.
The Show Parameters Before Running option in the panel is used to control whether to show the
configuration panel before rendering the library component each time the dashboard is run or
refreshed. For example, if a library component uses parameters, and you would like to specify
parameter values before loading the component rather than first loading the component and then
changing the parameter values so as to run the component the second time to get the desired result,
you can check this option to have the panel displayed by default.
●
Showing component information
Information about a component such as a library component's ID, the author and his/her e-mail
on
address, and the description about the component are provided. To view the information, click
the component title bar and select About from the drop-down list. A panel will be displayed showing
the information. You can click the OK button in the panel to close the panel.
●
Automatically arranging library components in the current dashboard
Sometimes you may drag many library components to random positions in a dashboard and would
like them to look neat, there is a simple way to do this: on the side bar, click the Arrange button
and select Arrange from the option list, the dashboard layout will
or click the Options button
then be adjusted immediately. Arrange is an instant action, clicking it once will arrange the layout
once, and in this sense it benefits when you seldom need to reorder the layout. In the case when
on the side bar and
frequent reorder of dashboard layout is required, click the Options button
click Auto Arrange on the option list. Then later each time a library component is resized, moved,
removed, or added, the dashboard body will be rearranged automatically so that the library
components will be placed tidy.
Manipulating data components
You can manipulate data components, which refer to crosstabs, tables, charts, and geographic maps, in
dashboards as shown below.
Applying a style to a data component
Right-click in the component, then on the shortcut menu, select a style from the Apply Style submenu.
Going through the data of tables, crosstabs and charts
Going actions enable you to switch among data groups freely for viewing different records without
having to create a new data component. They can be performed on table groups, crosstab column/row
headers, and data labels on the chart category/series axis as well as the legend entry labels.
Choose the proper one to meet your needs from the following:
●
●
●
●
Go To
Jumps to a different group by replacing the current.
Go to by Value
Jumps to another group while applying the current value being clicked on as a filter condition.
Go Down
Goes from a group which is non-bottom level in a predefined hierarchy to the one-level-lower group
while applying the current selected value as a filter condition.
Go Up
Jumps from a group which is non-top level in a predefined hierarchy to the one-level-higher group.
Note: When performing the go-down action, if the group objects are also defined with some links, you
can go down to the next level with a single click only when the click priority of the go-down action is
specified to be the highest at design time. Otherwise, you have to use the Go Down command on the
objects' shortcut menu to perform the action.
For example demonstration of them, refer to Going through the report data.
The go-to-by-value or go-down actions always happen along with the generation of a filter condition.
The filters are displayed as "FieldName:Value" at the bottom of the library components, in a row one by
one from left to right according to the time they are generated. When the row cannot hold all of the
filters, two buttons are displayed at the two ends of the row for scrolling through the filters to the left
and right. Each click on the button will show one hidden filter. To remove a filter condition, click X right
to it.
Customizing the data format of values in tables, crosstabs and charts
To customize the data format of the values of a field in a table or crosstab, right-click on any value of
the field, then select a format from the Format submenu, or input a format in the text box at the
bottom of the submenu and click Enter on the keyboard.
You can also customize the data format of the legend entry labels and data labels on the category and
series axes if they are of Number or Date/Time type. To do this, right-click on the labels and select the
required format from the Format submenu, or input a format in the text box at the bottom of the
submenu and click Enter on the keyboard.
Removing component level filters from a data component
On the shortcut menu of data components, there is an option Remove Filters which is used to remove
filter conditions generated via the configuration panel and via message delivery from the data
components. These two kinds of filters are referred to as component-level filters.
In dashboards you can also use sliders and filter controls to do filtering, however filters created by
sliders or filter controls are not under the control of the removing component level filter action, because
they are regarded as dashboard-level filters.
Manipulating a table
●
●
Sorting on a field
To sort the values of a field, right-click on any value of the field, then on the shortcut menu, select
Ascend or Descend from the Sort submenu. To remove the sort condition, select No Sort.
Filtering a detail field
You can use filter-related commands on the shortcut menu to filter the data in a table. To do this,
right-click on any value of the detail field by which you want to filter data, then from the Filter
submenu, specify to show the first/last N values of the field or a specific value, or click More to open
the Select Values dialog to specify the value. To remove filter condition created this way, use the
Remove Filter option on the Filter submenu.
Manipulating a crosstab
●
Sorting column/row header
To sort a column/row header, right-click on the header, then on the shortcut menu, select Ascend or
Descend from the Sort submenu. To remove the sort condition, select No Sort.
●
●
Switching crosstab fields
A convenient way to change the fields in a crosstab is by using the Switch command. To do this,
right-click a row/column/summary and select Switch Row/Switch Column/Switch Summary from
the shortcut menu. The fields available for the row/column/summary are listed in the submenu with
the current used field checked. Select the field you want to use to replace the current one.
Adjusting the width of crosstab fields according to the contents
When the contents in the field of a crosstab need more space to completely display, you can adjust
the width of the field according to its contents. To achieve it, right-click the field and
select Autofit from the shortcut menu.
Manipulating a chart
●
●
●
●
Swapping chart groups
You can switch data between the category and series axes, or between the category and value axes
of a chart if no field on the series axes. To do this, right-click in the chart, then on the shortcut
menu, click Swap Chart Groups.
Sorting category/series labels
You can sort the labels on the category or series axes of a chart in either descending or ascending
alphabetical order. To do this, right-click in the chart, then on the shortcut menu, select the required
order from the Sort Category or Sort Series submenu.
Changing the chart type
Right-click in the chart, then on the shortcut menu, locate Chart Type. From the drop-down menu,
select the desired chart type and its subtype.
Zooming in chart values
For a bar, bench, line, area or stock chart, you can select the values you are interested in to have
them zoomed in. To do this, drag the mouse from the start value to the end value you want to
select, then release the mouse. The selected values will be zoomed in. If you want to return to the
initial status, just click the return button
●
●
on the upper right corner of the chart paper.
Showing/Hiding the chart legend or legend label
Right-click the chart and select the corresponding show/hide option from the shortcut menu to show
or hide the legend or legend label. However, the legend will always be displayed at the export and
print results.
Configuring real time chart settings
For a real time chart, you can further configure it when inserted in a dashboard. To do this:
1. Right-click the chart and select Real-time Settings from the shortcut menu to display the Realtime Settings dialog.
2. Specify the time interval at which the chart will get data and refresh itself automatically in the
Refresh Interval text field.
3. Specify the most recent N records to be kept for the real time data on the chart in the Show
Most Recent text field.
4. Click the Incremental Fetch button to add the fields you want to use as the unique key of the
real time chart in the Unique Key dialog.
Once a unique key is defined, each time when the real time chart automatically updates itself,
duplicated data records will be filtered out based on the unique key. For instance, if you add the
fields Country and Product ID as the unique key of a real time chart, when a record with the
product ID 1 in USA has already been loaded into the chart, no more records of this product ID
in USA will be added to the real time chart because they have the same unique key value.
5. Check the Use Scrollable Bar checkbox if you want to use a scrollbar to control the visible
value range on the X axis of the chart, then specify how many data items will be selected on the
scrollbar and displayed on the axis by default, the percentage the scrollbar occupies the whole
size of the chart, and whether to show the thumbnail chart in the scrollbar.
6. Click OK to accept the settings and close the dialog.
●
Stopping or resuming a real time chart from refreshing
For a real time chart, you can stop or resume it from automatically refreshing by right-clicking it and
selecting the Pause Refresh or Resume command from the shortcut menu.
Manipulating geographic map group markers/areas
Going up/down on geographic map group markers/areas
●
❍
For the group level that is higher than some other group levels in a geographic map component,
point to its group marker/area, right-click it and select Go Down from the shortcut menu to jump
one group level down.
❍
●
For the group level that is lower than some other group levels in a geographic map component,
point to its group marker/area, right-click it and select Go Up from the shortcut menu to jump one
group level up.
Showing/Hiding geographic map group markers/areas
By default, all visible group markers/areas are shown. To hide them, right-click the geographic map
(not the group markers/areas) and select Hide Markers/Areas from the shortcut menu. If you want
to show them again, right-click the geographic map and select Show Markers/Areas from the
shortcut menu.
Filtering component data
When creating or editing dashboards, you can filter component data using two types of web controls:
sliders or filter controls.
Filter controls allow you to pick one or more random values from a list and are used with categorical or
nominal variables. You can choose one or more values from anywhere in the list and there is no mean
or median value calculation possible such as States and Countries.
Sliders allow you to pick one or more sequential values from a list and are used for interval variables
such as dates, times, quantity and currency variables where the slider represents the scale from lowest
to highest value and the middle represents the median value.
Think about what you need and choose the proper filtering tool.
Filtering scenarios
Both sliders and filter controls have the same filtering mechanism.
Filtering based on one field is a common usage. Bind a field to a slider or filter control, and then based
on the field to filter the data of the components created from the same data source as the field.
Another special usage is to filter components using different data sources. Choose a common field all
the data sources contain and then bind a slider or filter control with the common field in all the data
sources, that is, in the insertion dialog, select the common field under the nodes of all the data
sources.
For example, there are two components containing data from different data sources, and you want to
filter their data using one filter tool. The precondition is that both components have the field you want
to filter. For example, you would like the two components to show the data of a specific country. In
order to do this, insert a slider or a filter control according to your requirement into the dashboard
body, then in the insertion dialog, select both the country fields from the two data sources (different
data sources may use different names for the country field, for example, data source 1 uses "Country",
data source 2 uses "P_Country", in this case, you need to select both "Country" and "P_Country"), then
from the Apply To drop-down list, select the two components you want to filter. The filter tool will be
inserted in the dashboard body, and you can see it lists country names which come from the two data
sources. In the filter tool select one or more countries, then the two target components will be filtered
and only display the data of these selected countries.
When you bind a slider or filter control with multiple different fields, be sure the list of values in each
field match so that when you select a value, such as Country, P_Country and S_Country, it will match
the appropriate country field in each component. The logic is the values are OR that is
Field1=SelectedValue1 or Field2=SelectedValue1 or Field3=SelectedValue1. Therefore, when Field1,
Field2 and Field3 are used in different components you will see the records correctly in each
component.
When you bind a slider or filter control with multiple different fields which do not contain the same list
of values such as Country, Region and Territory, at runtime after you select values in the slider or filter
control, the filter condition will use OR logic to apply the selected values to all the fields of the slider or
filter control, for example, Field1=SelectedValue1 or Field2=SelectedValue1 or Field3=SelectedValue1.
In this case, when there are three fields but the list of values in each field do not match, the result will
have no matching records for two of the components and therefore become blank components. We
recommend that you use three different filter tools in cases like this.
Using sliders
To insert a slider to the dashboard body:
1. Click Show Resources
on the side bar to display the Resources panel.
2. From the Toolbox node, drag Slider to the destination in the dashboard body. The Insert Slider
dialog appears.
3. In the Title text field, input a title for the slider.
4. Choose whether the slider is used to specify a range of values or just a single value.
5. From the resource list, select the fields of the same data type to bind to the slider.
To filter components created from the same data source, select a field in the data source.
To filter components created from different data sources via one slider, find a common field these
data sources contain, then select the field in each of the data sources.
6. By default, all the values of the selected fields will be available for the slider, which may be too
many for a slider. However you can customize the values to show. To do this,
a. Click the Customize button to display the Customize Value dialog.
b. Uncheck the Select All option. You can then customize the values.
■
To specify values one by one, click
to add a value line, then in the line to type a value
or select a value from the drop-down list. Repeat the operation to add more values. To
remove a value, select its line and then click the
■
button.
To specify the value range, specify a value in the From and To text boxes respectively.
c. For fields of the Date/Time type, you can also specify a special function.
For details about the special functions, refer to Specifying special function for group by field
in the JReport Designer User's Guide.
d. Click OK to save the customized values. The customized values will be available on the slider
for choosing.
7. The Apply To drop-down list provides the components involving the selected fields. Select the
components which you want to filter.
8. Click OK. A slider bound with the specified fields will be inserted in the dashboard body. You can
then specify values in the slider to filter the specified components.
Using filter controls
To insert a filter control to the dashboard body:
1. Click Show Resources
on the side bar to display the Resources panel.
2. From the Toolbox node, drag Filter Control to the destination in the dashboard body. The Insert
Filter Control dialog appears.
3. In the Title text field, input a title for the filter control.
4. From the resource list, select the fields of the same data type to bind to the filter control.
To filter components created from the same data source, select a field in the data source.
To filter components created from different data sources via one filter control, find a common field
these data sources contain, then select the field in each of the data sources.
5. The Apply To drop-down list provides the components involving the selected fields. Select the
components which you want to filter.
6. Click OK. A filter control bound with the specified fields will be inserted in the dashboard body.
You can then specify values in the filter control to filter the specified components.
To easily locate the values you want in the filter control, you can make use of its quick search
toolbar. To display the toolbar, click
on the field name bar and then select a sub item to
launch the appropriate quick search toolbar. The button
on the field name bar is used to
cancel the selection of values in the filter control. For detailed usage about the quick search
toolbar, refer to Select Values dialog.
Notes:
●
●
When there are more than 300 values in a filter control, JReport will use Big Data Loading logic. In
this case, the Shift Key for multiple selection will not work.
Sometimes, when the position of a filter control is changed due to layout change, the advanced
search toolbar in the filter control may not follow the filter control but stay where it is.
Specifying parameter values
To specify parameter values to a dashboard:
on the side bar to display the Enter Parameter Values dialog which lists all the parameters used in the
Click
current dashboard. The way to specify a parameter value varies with the type and properties of the parameter. Here
are several ways you can use to specify parameter values:
●
In the parameter value combo box, input the value manually or select the required one from the drop-down list.
If you have chosen to automatically save parameter values, the saved value groups will be available on the top of
the parameters' value lists for selection.
●
Select or unselect the checkbox to specify a Yes/No value.
●
Click the button
●
Click the calendar button
to specify a date and time value using either calendar or expression in the Calendar
dialog. If you use an expression to specify the value, when you hover the mouse pointer over this value, a tip will
appear showing its expression. Click on the value, the expression will be displayed in the value text box and you
can edit the expression in the text box directly if you want. After editing, when you click elsewhere outside of the
value text box:
❍
❍
●
to specify multiple values in the Enter Values dialog.
If the edited expression is correct, a new value calculated by the expression will be displayed in the parameter
value text box.
If the edited expression is wrong, no value will be created and the expression itself will be displayed and
highlighted in red in the value text box. Correct the expression, or click the calendar button to specify a value.
Click the Use Saved Values button
and select a previously saved parameter value group to apply to the
dashboard. For details, see Manually saving parameter values.
To specify parameter values to a library component:
You can access the configuration panel of a library component to specify its parameter values. To do this, on the
and select Edit Setting from the drop-down list to display the
title bar of the library component, click
configuration panel, then specify the values in the panel and click OK to apply the values to the library component.
The Cancel button is used to close the configuration panel.
The Show Parameters Before Running option in the panel is used to control whether to show the configuration panel
before rendering the library component each time the dashboard is run or refreshed. For example, if a library
component uses parameters, and you would like to specify parameter values before loading the component rather
than first loading the component and then changing the parameter values so as to run the component the second
time to get the desired result, you can check this option to have the panel displayed before rendering by default.
Note: You are recommended not to use blank as the thousands separator in Number-typed parameter values under
French locale, otherwise your input will not be correctly recognized because of a JVM bug. For details, see http://
bugs.sun.com/view_bug.do;jsessionid=c8cdaf911b20fffffffffd9fc6340b30d670?bug_id=4510618.
This document also introduces some useful techniques for setting parameter values.
Saving parameter values for reuse
When specifying parameter values for dashboards, you may want to save the specified parameter values for reuse
next time. JReport provides two ways of saving. One is users decide when and which parameter values to save, the
other is JReport saves each applied or submitted parameter values automatically. When the saved number in either
way reaches the maximum, the oldest record will be removed. The number is calculated on a user-dashboard basis.
Take a dashboard with two parameters for an example, supposing the maximum number is set to 3. Each user can
save at most three groups of parameter values for the dashboard. Each group contains the values of the two
parameters.
To switch on the function of saving parameter values, go to the Profile > Customize Server Preferences > Advanced
tab, select Yes to the option Enable Saving Parameter Values, select a way to do the saving: Manually or
Automatically, and then specify a maximum number to limit the saved value groups which is called the auto
complete parameters list for each user-dashboard pair.
Manually saving parameter values
When you have chosen to manually save parameter values, the Use Saved Values button
will be available in the
Enter Parameter Values dialog. After clicking the button, a drop-down list that contains the lists of previously saved
parameter values will be displayed for you to choose one to apply.
The button
next to a drop-down list is used to delete the saved list from the list library.
You can also save the current parameter values as a whole marked as a list for reuse next time, by typing a name
. The parameter value
for the list in the text box which shows "Save current values into list" and then clicking
lists saved for a dashboard are limited. The maximum number is controlled by the option Maximum Number of Auto
Complete Parameters List in the Profile > Customize Server Preferences > Advanced tab. By default it is 3. When
the number of the saved parameter value lists reaches the maximum number, if you want to save another
parameter value list, it will overwrite the oldest one.
Using automatically saved parameter values
When you have chosen to automatically save parameter values, each time a user submits a group of parameter
values to a dashboard, the group is saved by JReport automatically. The next time the same user runs the
dashboard, the auto saved parameter values will be available in the parameters' value lists for selection in the Enter
Parameter Values dialog.
Customizing default parameter values
When specifying parameter values for a dashboard, if you would like the current specified parameter values to be
the default selected values in the Enter Parameter Values dialog next time when you run the dashboard, select the
Save as default option in the dialog (to make this option available, you need to make sure the Enable Setting
Default Parameter Values For Dashboard is selected in the Profile > Customize Server Preferences > Advanced tab).
The save as default option is a user-dashboard level setting, that is to say, it takes effect when both the same user
and dashboard are matched. This also applies to admin users, and therefore admin cannot customize the setting for
all users.
Sharing parameters between library components
A dashboard can have multiple library components and all these components are independent from each other.
When several components contain parameters which have the same name and come from the same catalog and at
the same time contain exactly the same values, by default these parameters are regarded as separate parameters
each connected to its own component. To submit a value to all these components you need to submit the value to
each of the parameters. However by sharing the parameters you only need to provide a value for one of them as a
representative of all the parameters. You need then only submit values to this parameter and all the components
will use the specified values.
What parameters can be shared
JDashboard supports sharing two types of parameters coming from different library components in the same
dashboard:
●
The same parameters
The parameters with the same name and coming from the same catalog.
For example, a parameter @Category comes from the catalog A.cat, and in a dashboard it is used by two library
components LC1 and LC2. So in the dashboard they are two parameters marked as [email protected] and LC2.
@Category. These two parameters are the same parameter and only require the user to specify one value for
them.
●
The same meaning parameters
The parameters that are not the same parameters but have the same parameter type and value data type. For
cascading parameters they should have the same hierarchies and each hierarchy have the same parameter value
type, then they can be shared as parameters with the same meaning even though the names are different.
For example, there are two parameters @Province and @State which have the same parameter type and value
type so they can both have the same meaning. For the cascading parameters like (@Country, @Province) and
(@Country, @State) which have the same hierarchies and each hierarchy has the same parameter value type so
they also can have the same meaning.
The rule for merging the values of the shared parameters
Within a sharing group, if all the shared parameters allows for type-in values, the merged value result is the union
of the values of all the parameters. The merged value names are distinct. However if any of the shared parameters
does not allow type-in values, the merged value result is the intersection of all the values.
Unexpected results after sharing parameters
Sometimes there may be unexpected parameter sharing that does no harm to the report system and report data,
but the dashboard result may be unexpected.
After sharing parameters, their values will be merged. The merged values result may be bigger or smaller than the
value lists of some of the shared parameters, which might lead to some values cannot be supported by some
components or some values can never be available to some components.
For example in the case of @Province and @State, if the parameters are shared then the list of values will be all
states and provinces. However, one library component may use a query that limits the data to US only, thus if the
user selects a Canadian province from the list the component will have no data.
How to share parameters
1. Click the Options button
on the side bar and then select Share Parameter from the option list. The Share
Parameters Setting dialog is displayed.
2. In the Share Parameters Setting dialog, select the parameters you would like to share by holding the Ctrl key.
If the selected parameters support being shared, the Share button will be enabled. Click the button. The
parameters will be added into one sharing group.
To add another parameter into a sharing group, select any parameter in the group while holding Ctrl and then
select the parameter, then click Share.
To remove parameters from a sharing group, select the parameters and then click Cancel Share which
appears in the place of the Share button.
3. Click OK to finish.
Saving dashboards
To save the changes you made to the current dashboard, click the Save button
button
on the side bar, or click the Options
and select Save from the option list.
If the dashboard is newly created and has not yet been saved, the Save As dialog will be displayed.
1. In the Save In section, browse to the folder where you want to save the dashboard in the server resource tree. The
folder may be Public Reports or My Reports. You can use the button
to return to the parent folder.
The resource table shows the resources in the current directory. Click the column names to change the order of the
report in the table list if required.
2. In the File Name box, enter the name of the dashboard or use the default name.
3. Click OK to save the dashboard.
To save a copy of a dashboard, click
dialog, and then do as above.
on the side bar and select Save As from the option list to show the Save As
After saving your dashboard into the server resource tree, you can browse to its directory on the JReport Console >
Resources page and run it directly just like you run a report.
To find a newly saved dashboard version, browse to select the row that the dashboard is in on the JReport Console >
Resources page, click Tools > Version on the task bar, the Dashboard Version panel will be displayed showing the
versions.
Note: You will not be able to save the dashboard to some locations if you do not have Write permission.
Exporting library components
Library components visible in the page panel can be exported, for example, library components that were created using JReport Designer and inserted
into dashboards via the Resources panel.
When exporting library component in a dashboard, you can choose in which layout you want the library components to be exported, system layout or
customized layout. In the system layout, JReport will calculate the positions of the library components in the dashboard following certain rule. If you
are not satisfied with the system layout, you can customize the layout by yourself to determine the position of each library component and specify
whether to export all the data of a table/crosstab or just the current page of the table/crosstab displayed in the dashboard. The customized layout can
be saved for all users who can access the dashboard.
To export using system layout:
1. Click the Export button
dialog is displayed.
on the side bar, or click the Options button
on the side bar and select Export from the option list. The Export
2. Select System Layout from the Layout drop-down list. The preview of the layout is displayed in the preview panel on the right. Sometimes you
may find that the layout is a little different from what you see in the dashboard.
3. In the Resources box, select the library components you are going to export. By default all exportable library components are listed and selected.
4. The order of the library components in the Resources box determines the order in which they will be exported. Click
exporting order if necessary.
and
to adjust the
5. Check the Show Component Title option if you want to show the library component titles in the export result.
6. Click the page navigation buttons on the toolbar of the preview panel to browse the pages if you want.
7. Click
to do the last setting and then export.
a. From the Export File Format drop-down list, specify the format for exporting the library components. For a format other than XML, all the
selected library components will be exported into one single file. For XML, each library component will be exported to a separate XML file.
When the exported result contains more than one file, all the files will be zipped.
b. In the File Name text field, specify a name to the exported result, which could be either a single file or a zipped package name.
c. Check Run Linked Report if you need to include linked report in the exported result file.
d. Click OK to start exporting.
To export using customized layout:
1. Click the Export button
dialog is displayed.
on the side bar, or click the Options button
on the side bar and select Export from the option list. The Export
2. Select Customize Layout from the Layout drop-down list. You can also select an existing customized layout to modify it.
3. Check the Show Component Title option if you want to show the library component titles in the export result.
4. To set the page properties, click the Page Setup button, then in the Page Setup dialog, specify the settings according to your requirement.
5. In the Design tab, customize the layout of the library components by making use of the following operations. The library components are
arranged using a tabular with each cell holding one component.
❍
Split or merge cells using the toolbar options:
❍
Drag a library component from the Resources box into a blank cell in the Design tab. A cell can hold only one library component.
❍
Delete a library component from a tabular cell, by using the shortcut menu option Remove.
❍
,
, and
.
For a table or crosstab, only its current view of data as displayed in the dashboard will be exported by default. If you want its full data to be
exported, right-click on the table or crosstab and select Filter from the drop-down list. Then in the Filter dialog, switch from Current View to All
and click OK.
6. Click the View tab to preview the layout. You can browse the pages and zoom in/out by clicking the corresponding toolbar buttons.
If you are satisfied with the layout and want to save it for future use, click
or
on the toolbar, then in the Save As dialog, provide a name
for the layout and click OK. The saved custom layouts will be available in the Layout drop-down list to all users who can access the dashboard.
For each of them, you can edit its name or delete it using the two buttons - Rename and Delete - appearing on the right when the mouse hovers
over the layout item on the drop-down list.
7. Click
, then in the Export dialog, do the last setting and start exporting.
See also Export dialog for details about the options in the dialog.
Tip: If you just want to export a single library component, there is a more convenient way.
1. Click
on the title bar of the library component and select Export from the drop-down list. The Export dialog is displayed.
2. In the Export dialog, choose the format to which you want to export the library component, then click OK.
However, using this way, if the library component is linked with other reports, you cannot control whether to generate the linked reports while
exporting. The linked reports will not be included in the exported result for all time.
Printing library components
Library components visible in the page panel can be printed, for example, library components that were created using JReport Designer and
inserted into dashboards via the Resources panel.
When printing in JDashboard, you can choose in which layout you want the library components to be printed, system layout or customized layout.
In the system layout, JReport will calculate the positions of the library components in the dashboard following certain rule. If you are not satisfied
with the system layout, you can customize the layout by yourself to determine the position of each library component and specify whether to print
all the data of a table/crosstab or just the current page of the table/crosstab displayed in the dashboard. The customized layout can be saved for all
users who can access the dashboard.
To print using system layout:
1. Click the Print button
on the JDashboard side bar, or click the Options button
The Print dialog is displayed.
on the side bar and select Print from the option list.
2. Select System Layout from the Layout drop-down list. The preview of the layout is displayed in the preview panel on the right. Sometimes
you may find that the layout is a little different from what you see in the dashboard.
3. In the Resources box, select the library components you are going to print. By default all printable library components are listed and selected.
4. The order of the library components in the Resources box determines the order in which they will be printed. Click
printing order if necessary.
and
to adjust the
5. Check the Show Component Title option if you want to show the library component titles in the print result.>
6. Click the Printer Properties button. In the Printer Properties dialog, configure the printer properties as required.
7. Click the page navigation buttons on the toolbar of the preview panel to browse the pages if you want.
8. When done, click
on the toolbar to start printing.
To print using customized layout:
1. Click the Print button
on the JDashboard side bar, or click the Options button
The Print dialog is displayed.
on the side bar and select Print from the option list.
2. Select Customize Layout from the Layout drop-down list. You can also select an existing customized layout to modify it.
3. Check the Show Component Title option if you want to show the library component titles in the print result.
4. Click the Printer Properties button. In the Printer Properties dialog, configure the printer properties as required.
5. To set the page properties, click the Page Setup button, then in the Page Setup dialog, specify the settings according to your requirement.
6. In the Design tab, customize the layout of the library components, then preview it in the View tab. For how to customize the layout, refer to
Exporting using customized layout.
7. When done, click
on the toolbar to start printing.
See also Print dialog for details about the options in the dialog.
Setting JDashboard as the server home page
Setting JDashboard as the JReport Server user console home page allows for a faster and easier access
to frequently visited dashboards with their latest data. The feature saves JDashboard status as the
contents of the home page, such as which dashboards are open and which dashboard is active. Then
you will be able to easily access the JDashboard with the saved status by one of the following ways:
●
●
Log onto the JReport Console page and you will be directed to the Home tab right away which
displays the JDashboard. The Home tab is available after you have set JDashboard as the server
home page.
Click the Home tab on the system toolbar of the JReport Console page to switch to the JDashboard.
To set JDashboard as the server home page:
1. In the Profile > Customize Server Preferences > General tab on the JReport Administration or
JReport Console page, set the option Use JDashboard as Server User Console Home Page to Yes
to enable setting JDashboard as server home page.
2. In JDashboard, open the dashboards that you are going to view a lot and make sure they have
been saved. Focus on the dashboard you would like to see first once the JDashboard is loaded,
then click the Options button
on the side bar and you will see Set as Server Home is enabled
on the option list. Click the option to set the current JDashboard status as the home page.
In the same JDashboard window, you can set the home page at any time you want. The last time you
do this before exiting JDashboard will take effect.
To cancel setting the home page, in the Profile > Customize Server Preferences > General tab on the
JReport Administration or JReport Console page, uncheck Yes for the option Use JDashboard as Server
User Console Home Page.
Running dashboards via URL
Similar to reports, dashboards can be created or run directly from your application. JDashboard uses /
{context_root}/dashboard/app/entry/run.jsp as the URL entry. Here {context_root} is the
servlet's context root when deployed in a WAR or EAR file as a servlet.
Creating a new dashboard
To create a new dashboard from URL, simply use /{context_root}/dashboard/app/entry/run.jsp.
For example, run the URL http://localhost:8888/dashboard/app/entry/run.jsp, and JDashboard
will be opened with a new blank dashboard in it. You can then begin to build your dashboards.
Visiting JDashboard as the server home page
After JDashboard has been set as the server user console home page, you can use a URL to access the
home page.
Parameter name: jrd_lastsession
Parameter value: true/false
Examples:
●
●
http://localhost:8888/dashboard/app/entry/run.jsp?jrd_lastsession=true
http://<IP>:<port>/jreport/dashboard/app/entry/run.jsp?jrd_lastsession=true, here
jreport is the servlet context root.
Opening specific dashboards
JReport provides parameters for developer users to run dashboards via URLs. Some parameters are
encapsulated as JSON (JavaScript Object Notation) objects. Therefore, it will help if you obtain some
knowledge on JSON to understand the syntax more clearly. When composing the URL, you need to use
URL encoding to avoid errors. To encode URLs by JavaScript, the function encodeURI is recommended.
●
jrd_resext={
"active":0, // The index number of the dashboard that will be active once the JDashboard is loaded. 0
means the first dashboard specified in the value list of the parameter "reslst", 1 the second
dashboard, 2 the third, and so on.
"reslst":[
// Specify the dashboards to open. The order of the dashboards specified here reflects the order they
are displayed in the JDashboard.
{"name":"DashboardFileNameWithFullPath", // The dashboard file name with its
full path. The path could be a disk path or a server resource tree path. For the
latter, it could be either in the My Reports folder (/USERFOLDERPATH/admin/) or
in the Public Reports folder (/).
"ver":"-1", // Optional: The version number of the dashboard. -1 means the latest
version.
"real":"false", // Optional. Value: true/false. true means the resource path is a
real disk path and false means a server resource tree path. When it is a real path,
"real":"true" must be specified.
"type":"40", // Indicates it is a dashboard.
"param_page":"true", // Optional. Value: true/false. Specify whether to pop up
the parameter dialog if the dashboard uses parameters.
"dsh_params":[
// Specify the parameter values used in the dashboard.
{"lc_names":["lc1","lc2",...], // Optional: lc1 and lc2 can be either
of the following:
❍
❍
The names of the library components in the dashboard, with full
path in the server resource tree, either in the My Components
folder (/USERFOLDERPATH/admin/) or in the Public Components
folder (/COMPONENT_LIB/). For example, /COMPONENT_LIB/
SampleReports/Sales Bar.lc.
The IDs of the library components. The ID of a library component
can be known in the library component's About panel. To access
on the component's title bar and select About
the panel, click
from the drop-down list.
"jrd_params":{"parameter1":"value1","parameter2":
["value1","value2",...]} // If lc_names and jrd_params are specified
together, the parameters here are applied to the library components
given by lc_names, otherwise to the dashboard. When both
dashboard level and library component level parameters exist in the
URL, the order to apply parameters will be: the dashboard first, and
then the library components. When several library components are
the same in the dashboard, the parameters specified to one of them
will also work on the others. In the case when the URL does not
specify parameters for a specific library component but the
dashboard level parameters are available, if later a new library
component is added into the dashboard, it will use the parameter
values in the URL. When a library component is set to use a new
connection in the URL, then when adding it into the current
dashboard, the library component uses the new connection.
}
]
},
... // Specify more dashboards following the above format.
]
}
●
jrd_dashboard_mode=view
// Required when you would like JDashboard to open in the view mode. When this parameter is not
provided in the URL, JDashboard runs in the edit mode.
Examples:
●
http://<IP>:<port>/jreport/dashboard/app/entry/run.jsp?jrd_resext=
{"active":0,"reslst":[{"name":"/USERFOLDERPATH/admin/Dashboard 1.dsh","ver":"-1"}]},
here jreport is the servlet context root.
●
http://localhost:8888/dashboard/app/entry/run.jsp?jrd_resext={"active":1,"reslst":
[{"name":"/USERFOLDERPATH/admin/Dashboard 2.dsh"},{"name":"/USERFOLDERPATH/admin/
Dashboard 1.dsh"}]}
In this case, after JDashboard is displayed, Dashboard 2.dsh and Dashboard 1.dsh are open and
follow the order from left to right, and Dashboard 1.dsh is active by default.
●
http://localhost:8888/dashboard/app/entry/run.jsp?jrd_resext={"active":1,"reslst":
[{"name":"/USERFOLDERPATH/admin/Dashboard 2.dsh"},{"name":"/USERFOLDERPATH/admin/
Dashboard 1.dsh"}]}&jrd_dashboard_mode=view
The only difference between this example and the second one above is that this URL runs JDashboard
in the view mode while the above example runs JDashboard in the edit mode.
●
Set parameters for dashboard only:
http://localhost:8888/dashboard/app/entry/run.jsp?jrd_resext={"active":0,"reslst":
[{"name":"/USERFOLDERPATH/admin/Dashboard 1.dsh","dsh_params":[{"jrd_params":
{"P_StartDate":"01/01/2006","P_EndDate":"12/31/2007"}}]}]}
●
Set parameters for library components only:
http://localhost:8888/dashboard/app/entry/run.jsp?jrd_resext={"active":0,"reslst":
[{"name":"/USERFOLDERPATH/admin/Dashboard 1.dsh","dsh_params":[{"lc_names":["/
COMPONENT_LIB/SampleReports/Country Sales by Category.lc","/COMPONENT_LIB/
SampleReports/Sales Bar.lc"],"jrd_params":
{"P_StartDate":"01/01/2006","P_EndDate":"12/31/2007"}}]}]}
●
Set parameters for both dashboard and library components:
http://localhost:8888/dashboard/app/entry/run.jsp?jrd_resext={"active":0,"reslst":
[{"name":"/USERFOLDERPATH/admin/Dashboard 1.dsh","dsh_params":[{"jrd_params":
{"P_StartDate":"01/01/2006","P_EndDate":"12/31/2007"}},{"lc_names":["/COMPONENT_LIB/
SampleReports/Country Sales by Category.lc","/COMPONENT_LIB/SampleReports/Sales Bar.
lc"],"jrd_params":{"P_StartDate":"01/01/2006","P_EndDate":"12/31/2007"}}]}]}
●
Run a dashboard from the real path:
http://localhost:8888/dashboard/app/entry/run.jsp?jrd_resext={"active":0,"reslst":
[{"name":"/home/admin/Jinfonet/Server/history/1/admin959238972/demo1.dsh","ver":"1","real":"true"}]}&jrs.authorization=YWRtaW46YWRtaW4%3D
Opening dashboards and reports via one URL
It is similar to opening multiple dashboards.
jrd_resext={
"active":0, // The index number of the dashboard/report that will be active once the
JDashboard is loaded. 0 means the first dashboard/report specified in the value list of the
parameter "reslst", 1 the second, 2 the third, and so on.
"reslst":[
// Specify the dashboards and reports to open. The order of them specified here reflects
the order they are displayed in the JDashboard.
{
"name":"ResourceFileNameWithFullPath", // The dashboard/report file
name with its full path. The path could be a disk path or a server resource
tree path. For the latter, it could be either in the My Reports folder (/
USERFOLDERPATH/admin/) or in the Public Reports folder (/).
"ver":"-1", // Optional: The version number of the dashboard/report. -1
means the latest version.
"real":"false", // Optional. Value: true/false. true means the resource path
is a real disk path and false means a server resource tree path. When it is
a real path, "real":"true" must be specified.
"type":"xx", // Indicates the type of the resource. Value: 40/44/45. 40
means it is a dashboard, 44 a web report, and 45 a page report.
"param_page":"true", // Optional. Value: true/false. Specify whether to
pop up the parameter dialog if the report uses parameters.
"dependence":{ // For reports only.
"catalog":{ // Specify the catalog of the report.
"name":"ResourcePath/CatalogName", // The
resource path of the catalog used by the
report. It could be a disk path or a server
resource tree path.
"ver":"-1", // Optional: The version number of
the catalog. -1 means the latest version.
"real":"false" // Optional: true means the
resource path is a real disk path and false
means a server resource tree path.
}
},
"dsh_datasources":[{
// Specify the data source used in the dashboard/report. For a dashboard,
one or more groups can be specified. For a report, only one can be
specified.
"lc_names":["lc1","lc2",...], // Optional. Only for dashboards.
"jrd_datasources":[{datasource1},{datasource2},...] // For
dashboards, refer to jrd_datasources. For web reports, refer
to jrd_datasources.
}],
"dsh_params":[
// Specify the parameter values used in the dashboard/report. For a
dashboard, one or more groups can be specified. For a report, only one can
be specified.
{
"lc_names":["lc1","lc2",...], // Optional. Only for dashboards.
"jrd_params":{"parameter1":"value1","parameter2":
["value1","value2",...]}
}
]
},
...
// Another way to specify a report to open.
{
"name":"a part of running report URL", // Specify a part of a URL as the
value. The URL should be the one used for running the report via the
tryView.jsp or runReport.jsp. The value extracts the URL part started with
"tryView.jsp" or "runReport.jsp" and encodes the URL reserved words such
as "?" and "&". For example, the extracted original URL is "tryView.jsp?jrs.
cmd=jrs.try_vw&jrs.report=%2fSampleReports%2fShipmentStatus.wls&jrs.
catalog=%2fSampleReports%2fSampleReports.cat&jrs.result_type=8", the
encoded URL that can be set as the value will be "tryView.jsp%3Fjrs.cmd%
3Djrs.try_vw%26jrs.report%3D%2FSampleReports%2FShipmentStatus.wls
%26jrs.catalog%3D%2FSampleReports%2FSampleReports.cat%26jrs.
result_type%3D8". "type":"46/47" // The type of the report. Value: 46/47.
46 means it is a web report, 47 a page report.
}
]
}
Examples:
●
Open a dashboard and a report:
http://localhost:8888/dashboard/app/entry/run.jsp?jrd_resext={"active":1,"reslst":[{"name":"/
USERFOLDERPATH/admin/Dashboard 2.dsh","ver":"-1"},{"name":"/SampleReports/ShipmentStatus.
wls","ver":"-1","type":"44","param_page":"true","dependence":{"catalog":{"name":"/SampleReports/
SampleReports.cat","ver":"-1"}}}]}&jrs.authorization=YWRtaW46YWRtaW4%3D
●
Open a dashboard, a web report, and a page report:
http://localhost:8888/dashboard/app/entry/run.jsp?jrd_resext={"active":1,"reslst":[{"name":"/
USERFOLDERPATH/admin/Dashboard 2.dsh","ver":"-1"},{"name":"/SampleReports/Coffee Sales.
wls","ver":"-1","type":"44","dependence":{"catalog":{"name":"/SampleReports/SampleReports.
cat","ver":"-1"}}},{"name":"/SampleReports/Cascade Parameters.cls","ver":"1","type":"45","dependence":{"catalog":{"name":"/SampleReports/SampleReports.cat","ver":"1"}}}]}&jrs.authorization=YWRtaW46YWRtaW4%3D
●
Open two dashboards and a report in the view mode of JDashboard:
http://localhost:8888/dashboard/app/entry/run.jsp?jrd_resext={"active":0,"reslst":[{"name":"%
2fSampleReports%2fBanded_Link.cls","ver":"-1","real":"false","type":45"},{"name":"/WebDemo/
medicare dashboard.dsh","ver":"-1"},{"name":"%2fSampleReports%2fCoffee%20Sales.wls","ver":"1","real":"false","type":"44"}]}&jrd_dashboard_mode=view&jrs.authorization=YWRtaW46YWRtaW4%
3D
●
Open a dashboard by specifying the name and path and two reports by specifying the URL:
http://localhost:8888/dashboard/app/entry/run.jsp?jrd_resext={"active":1,"reslst":[{"name":"/
USERFOLDERPATH/admin/Dashboard 2.dsh","ver":"-1"},{"name":"tryView.jsp%3Fjrs.cmd%3Djrs.
try_vw%26jrs.report%3D%2FSampleReports%2FShipmentStatus.wls%26jrs.catalog%3D%
2FSampleReports%2FSampleReports.cat%26jrs.result_type%3D8","type":"46"},{"name":"tryView.
jsp%3Fjrs.cmd%3Djrs.try_vw%26jrs.report%3D%2fSampleReports%2fCorporate+Overview.cls%
26jrs.catalog%3D%2fSampleReports%2fSampleReports.cat%26jrs.result_type=8","type":"47"}]}
&jrs.authorization=YWRtaW46YWRtaW4%3D
http://localhost:8888/dashboard/app/entry/run.jsp?jrd_resext={"active":1,"reslst":[{"name":"/
USERFOLDERPATH/admin/Dashboard 2.dsh","ver":"-1"},{"name":"runReport.jsp%3Fjrs.cmd%3Djrs.
try_vw%26jrs.report%3D%2FSampleReports%2FShipmentStatus.wls%26jrs.catalog%3D%
2FSampleReports%2FSampleReports.cat%26jrs.result_type%3D8","type":"46"},{"name":"runReport.
jsp%3Fjrs.cmd%3Djrs.try_vw%26jrs.report%3D%2fSampleReports%2fCorporate+Overview.cls%
26jrs.catalog%3D%2fSampleReports%2fSampleReports.cat%26jrs.result_type=8","type":"47"}]}
&jrs.authorization=YWRtaW46YWRtaW4%3D
Switching data source connection in URL
Add a property in jrd_resext:
●
"dsh_datasources":[
// Specifies the data sources for switching the dashboard and/or the specific library components in
the dashboard to.
{
"lc_names":["lc1","lc2",...], // Optional.
"jrd_datasources":[{datasource1},{datasource2},...] // If lc_names and
jrd_datasources are specified together, the data sources here are applied to the
library components given by lc_names, otherwise to the dashboard. When both
dashboard level and library component level data sources exist in the URL, the
order to apply data sources will be: the dashboard first, and then the library
components. When several library components are the same in the dashboard,
the data source specified to one of them will also work on the others. The
property "ds" is optional. If "ds" is not specified, the new connection here applies
to all involved data sources. If "ds" is specified, the new connection applies only to
the same data source as that specified by "ds".
}
]
Example:
http://localhost:8888/dashboard/app/entry/run.jsp?jrd_resext={"active":0,"reslst":
[{"name":"/USERFOLDERPATH/admin/Dashboard 1.dsh","dsh_datasources":[{"jrd_datasources":
[{"ds":"Data Source 1","uid":"test","pwd":"1234","type":"0","url":"jdbc:oracle:thin:
@127.0.0.1:1521:ora8i","driver":"oracle.jdbc.driver.OracleDriver"}]},{"lc_names":["/
COMPONENT_LIB/SampleReports/Country Sales by Category.lc","/COMPONENT_LIB/SampleReports/
Sales Bar.lc"],"jrd_datasources":[{"ds":"Data Source
1","uid":"test","pwd":"1234","type":"0", "url":"jdbc:oracle:thin:@127.0.0.1:1521:
ora8i","driver":"oracle.jdbc.driver.OracleDriver"}]}]}]}
Note: In the case when the URL does not specify a data source connection for a specific library
component but a dashboard level connection is available, if later a new library component is added into
the dashboard, it will use the connection in the URL.
Authentication parameters
jrs.authorization, jrs.auth_uid and jrs.auth_pwd are supported.
Example for jrs.authorization:
http://<IP>:<port>/jreport/dashboard/app/entry/run.jsp?jrd_resext={"active":0,"reslst":[{"name":"/
USERFOLDERPATH/admin/Dashboard 1.dsh","ver":"-1"}]}&jrs.authorization=YWRtaW46YWRtaW4%3D
Example for jrs.auth_uid and jrs.auth_pwd:
http://<IP>:<port>/jreport/dashboard/app/entry/run.jsp?jrd_resext={"active":0,"reslst":[{"name":"/
USERFOLDERPATH/admin/Dashboard 1.dsh","ver":"-1"}]}&jrs.auth_uid=admin&jrs.auth_pwd=admin
Running and editing reports in JDashboard
In addition to running reports from the JReport Server user console page, JDashboard also provides an
entry for displaying reports directly from your application. When using JDashboard, you do not have to
switch to the server user console page in order to open a report and edit it.
Viewing a report in JDashboard launches its fully functional editor together with the report in a tab in
JDashboard. The tab name is the report name. When it is a page report, the corresponding page report
editor will be available, and for a web report, the web report editor will be available. With the report
editor, reports can be edited directly in JDashboard.
on the side bar to open the Resources
To open a report in JDashboard, click Show Resources
panel. Then in the Reports node, browse to the target report and drag it to the editing area, the report
will be loaded. If the report uses parameters, you will be asked to specify the parameter values first
before the report is displayed.
For how to edit a page report (.cls), refer to Page Report Studio - Interactive Reports. For how to edit a
web report (.wls), refer to Editing web reports in Web Report Studio.
To close an open report, click x on the report tab or on the toolbar in the tab.
Opening Visual Analysis in JDashboard
If your JReport Server is enabled with Visual Analysis, you can access Visual Analysis directly from JDashboard without
having to switch to the server user console. Visual Analysis is loaded in JDashboard as a tab with full functionalities for you
to perform data analysis with.
Accessing Visual Analysis
In the edit mode of JDashboard, there are several ways to access Visual Analysis:
●
On the dashboard title bar, leave the mouse cursor on the + button beside the rightmost tab for one second until a dropdown menu displays, then select New Analysis from the menu.
●
On the side bar, click the New button
●
On the side bar, click the Options button
and then select New Analysis.
and then select New > Analysis.
Opening an existing visual analysis template
1. In the edit mode of JDashboard, click the Open button
on the side bar, or click the Options button
Open from the option list. The Open Document dialog is displayed.
and select
2. Browse to the desired folder, select the visual analysis template you want to open and then click OK, or simply doubleclick the visual analysis template to open it.
Visual Analysis
Visual Analysis is a WYSIWYG product to visualize the result of every step of your work. Simply by
dragging and dropping data fields to the layout module, you are able to experience the detailed
building up of crosstabs and charts step by step visually.
Business views are the data sources used in Visual Analysis. Each time you can perform data analysis
based on one business view, and later you can save the result as a visual analysis template into the
server resource tree. However, Visual Analysis does not support the customization of parameter values,
so if a business view contains parameters, the default parameter values will be applied when you
perform visual analysis on the business view.
Visual Analysis can work in both remote and integration environments.
Visual Analysis is a separately licensed feature of JReport Server. It is installed together
with JReport Server so only the license key needs to be updated to enable it to run. To
find out how to license Visual Analysis please contact Jinfonet sales at [email protected] or
contact your Enterprise Account Manager.
This chapter covers the following topics:
●
Visual Analysis window elements
●
Starting Visual Analysis session
●
Accessing Visual Analysis via URL
●
Performing visual analysis
●
Saving visual analysis templates
Notes:
●
●
Visual Analysis cannot run on Internet Explorer 8.
Visual Analysis may not work well on Google Chrome. You can try disabling GPU accelerated 2D
canvas: access the URL chrome://flags, disable accelerated 2D canvas, and then relaunch Chrome.
Visual Analysis window elements
The Visual Analysis window contains the following sections:
●
Toolbar
●
Left panels
●
Presentation area
Toolbar
Menu
●
●
●
●
●
●
●
●
●
New
Starts a new visual analysis in a new Visual Analysis window.
Open
Opens an existing visual analysis template in a new Visual Analysis window via the Open dialog.
Save
Saves the changes to the current visual analysis template.
Save As
Saves the current visual analysis template with a different name or location in the Save As dialog.
Undo
Undoes the last operation.
Redo
Reverses the operation of Undo.
Clear Filters
Clears the filters in the Filters panel.
Swap
Exchanges the row headers and the column headers.
View
Specifies the view mode:
❍
❍
❍
Normal View
The JReport smart layout. Scroll bar will be provided horizontally or vertically if the available space
cannot hold all the data.
Fit Height
All vertical data are displayed according to the available height.
Fit Width
All horizontal data are displayed according to the available width.
❍
Fit Visible
The combination of Fit Width and Fit Height. All data are displayed horizontally and vertically
according to the available space.
In the Fit XXX mode, the column header height, row header width, and the header font size is the
same as that in Normal View. The text in the header will be cut if it cannot be fully displayed.
●
●
Help
Displays the Visual Analysis user's guide.
Exit
Exits the Visual Analysis window.
Undo
Undoes the last operation.
Redo
Reverses the operation of Undo.
Refresh
Refreshes the current data result.
Open
Opens an existing visual analysis template in a new Visual Analysis window via the Open dialog.
Save
Saves the changes made during the visual analysis.
Save As
Saves the current visual analysis template with a different name or location in the Save As dialog.
Swap
Exchanges the columns and rows in the data presentation area.
View mode
Specifies the view mode from the drop-down list.
Left panels
Resources panel
This panel lists all the fields in the selected business view. It provides data resources to the Filters
panel and to the presentation area.
Filters panel
This panel lists the filters being used. You can add new filters by dragging group fields from the
Resources panel into the Filters panel. The newly added filters provide full values by default.
Presentation area
This is where you perform visual analysis actions. Follow the instructions in this area to drag data fields
from the Resources panel to the desired positions in the presentation area. As you start to drag a field,
the possible places where you can drop it are highlighted with a red border. As you add groups to the
rows or columns the crosstab expands to include the new group and all of the aggregations are
recalculated.
Only group and aggregation fields can be added into the data presentation area.
The following are details about each element:
Drag a group field from the Resources panel and drop it to this control box, and it will become a
column header. You can drag multiple data fields here one by one. When there are already existing
fields here you can drop them in front or in back of each existing field. A black arrow appears to
indicate the position it will take when you drop it.
to add a new field. Click
and select the required one
You can also make use of the button
from the drop-down list which is a filtered result of all the group fields in the business view. The field
will be added as the rightmost column by default.
To adjust the order of the columns, drag one and drop it to a new location.
To remove a field from the column, drag and drop it outside of the control box, or click the field and
then select Delete from the drop-down menu.
Drag an aggregation field from the Resources panel and drop it to this control box, and it will become a
column header. The field is used to draw axes horizontally at the bottom. You can drag multiple data
fields here one by one. When there are already existing fields here you can drop them in front or in
back of each existing field. A black arrow appears to indicate the position it will take when you drop it.
You can also make use of the button
to add a new field. Click
and select the required one
from the drop-down list which is a filtered result of all the aggregation fields in the business view. The
field will be added as the rightmost column by default.
To remove a field from the column, drag and drop it outside of the control box, or click the field and
then select Delete from the drop-down menu.
Drag a group field from the Resources panel and drop it to this control box, and it will become a row
header. You can drag multiple data fields here one by one. When there are already existing fields here
you can drop them above or below each existing field. A black arrow appears to indicate the position it
will take when you drop it.
to add a new field. Click
and select the required one
You can also make use of the button
from the drop-down list which is a filtered result of all the group fields in the business view. The field
will be added as the topmost row by default.
To remove a field from the row, drag and drop it outside of the control box, or click the field and then
select Delete from the drop-down menu.
Drag an aggregation field from the Resources panel and drop it to this control box, and it will become a
row header. The field is used to draw axes vertically on the left. You can drag multiple data fields here
one by one. When there are already existing fields here you can drop them above or below each
existing field. A black arrow appears to indicate the position it will take when you drop it.
You can also make use of the button
to add a new field. Click
and select the required one
from the drop-down list which is a filtered result of all the aggregation fields in the business view. The
field will be added as the topmost row by default.
To remove a field from the row, drag and drop it outside of the control box, or click the field and then
select Delete from the drop-down menu.
Display Type
Specifies the display type of the data values displayed in the data presentation area.
Text
The data values are displayed in text. This type requires that a data field is defined by the label legend
in the legend section.
Bar
The data values are displayed as bar charts.
Line
The data values are displayed as line charts.
Pie
The data values are displayed as pie charts.
Shape
The data values are displayed as shape diagrams.
Legend
This section introduces all available legend types. Some legend types are specific to certain display
types.
●
Color legend
●
Size legend
●
Label legend
●
Slice legend
●
Shape legend
Color legend
The color legend
allows you to identify the members of a data field by colors.
Data fields that can be bound with the color legend should be either of the following:
●
One or more group fields.
●
One single aggregation field.
Multiple aggregation fields and the combination of group and aggregation fields are not supported.
For a single field, each field member is marked by a distinct color. For multiple group fields, each
combination of the members of the fields is marked by a distinct color.
Adding data fields
To add a data field to the color legend, drag the field from the Resources panel and drop it to the Color
button
. The field and its members will be listed in the lower area of the Legend section. Each
member will be marked by a distinct color.
If group fields are already added in the color legend, dragging an aggregation field to the color legend
will remove all the existing group fields from the color legend.
If an aggregation field is already added in the color legend, dragging another group field or aggregation
field to the color legend will remove the existing aggregation field from the color legend.
Replacing a data field
To replace a group field in the color legend with another group field, drag the new field and drop it to
the existing field name in the color legend until the name bar is highlighted.
To replace an aggregation field with another aggregation field, drag the new field and drop it to the
Color button
highlighted.
or drop it to the existing field name in the color legend until the name bar is
Changing the field order
When multiple group fields are bound with the color legend, you can change their order. By default the
bound fields are listed from top to bottom. Drag a field that is not at the bottom of the list to the Color
button
and the field will be moved to the bottom of the list.
Removing a data field
To remove a data field from the color legend, drag and drop the field name bar outside of its position.
Customizing color when color legend is bound with no field
If no field is bound with the color legend, the color legend will use one single color.
Click the Color button
and you will be able to select a color in the color palette, or click More
Colors to access the Color Picker dialog in which you can select a color within a wider range.
●
●
Recent Colors
Recent used colors are listed here. It is session level. You can click a recent color to apply it.
More Colors
Opens the Color Picker dialog.
Customizing color when color legend is bound with fields
If group fields are bound with the color legend, the colors will be discrete colors that come from a
pattern. To change the color, click the Color button
to access the Edit Color dialog.
If an aggregation field is bound with the color legend, the colors will be gradient colors which also come
from a pattern. To change the color, click the Color button
to access the Edit Gradient Color dialog.
Size legend
The size legend
allows you to identify the members of a data field by sizes.
Drag a data field from the Resources panel and drop it to the Size button
the lower area of the Legend section.
. The field will be listed in
The size legend can be bound with at most one data field. Drag a different data field to the Size button
which is already bound with a field, the new field will replace the existing field.
To remove the size legend field, drag and drop the field name bar outside of its position.
Click the Size button
from 1% to 200%.
and you will be able to adjust the size legend in percentage. The range is
Label legend
The label legend
provides label text to the members of data fields. Multiple data fields can be bound
with the label legend.
Adding data fields
To add a data field to the label legend, drag the field from the Resources panel and drop it to the Label
button
. The field will be listed in the lower area of the legend section.
Replacing a data field
To replace a data field in the label legend with another data field, drag the new field and drop it to the
Label button
highlighted.
or drop it to the existing field name in the label legend until the name bar is
Changing the field order
When multiple data fields are bound with the label legend, you can change their order. By default the
bound fields are listed from top to bottom. Drag a field that is not at the bottom of the list to the Label
button
and the field will be moved to the bottom of the list.
Removing a data field
To remove a data field from the label legend, drag and drop the field name bar outside of its position.
Slice legend
The slice legend
allows you to identify the members of an aggregation field by sections divided
from the center point in pies. It is available to the Pie display type.
The slice legend can be bound with at most one aggregation field. Drag an aggregation field from the
Resources panel and drop it to the Slice button
Legend section.
. The field will be listed in the lower area of the
Drag a different aggregation field to the Slice button
field will replace the existing field.
which is already bound with a field, the new
To remove the slice legend field, drag and drop the field name bar outside of its position.
The slice legend field can be moved to another legend. Drag the field to the corresponding legend
button, or click the field name bar and select the proper item:
●
●
●
As Color
Removes the field from the slice legend and adds it to the color legend.
As Size
Removes the field from the slice legend and adds it to the size legend.
As Label
Removes the field from the slice legend and adds it to the label legend.
Shape legend
The shape legend
allows you to identify the members of a data field by shapes. It is available to
the Shape display type.
Drag a data field from the Resources panel and drop it to this button. The field will be listed in the
lower area of the Legend section.
The shape legend can be bound with at most one data field. Drop a different data field to the Shape
button
which is already bound with a field, the new field will replace the existing field.
To remove the shape legend field, drag and drop the field name bar outside of its position.
Customizing shape when color legend is bound with no field
If no field is bound with the shape legend, the shape legend will use one shape. To change the shape,
click the Shape button
and then select a shape from the drop-down list.
The first shape is the default applied shape.
Customizing shape when color legend is bound with a field
If a data field is bound with the shape legend, to change the shapes, click the Shape button
access the Edit Shapes dialog.
to
Starting Visual Analysis session
To start a new Visual Analysis session from the JReport Console:
1. On the JReport Console > Resources page, click New > Analysis.
2. In the Select Business View dialog, select the required one and click OK.
3. The Visual Analysis window will be loaded.
To start a Visual Analysis session on a saved visual analysis template:
1. On the JReport Console > Resources page, browse to the visual analysis template, then do one of the following:
❍
Click the name of the visual analysis template in the Name column of the Resources page.
❍
Select the visual analysis template row and click Run > Run on the task bar of the Resources page.
❍
Select the visual analysis template row, right-click in the row and select Run from the shortcut menu.
❍
Put the mouse pointer over the visual analysis template row and click the Run button
on the floating toolbar.
2. The Visual Analysis window will be loaded.
To start a new Visual Analysis session during a Visual Analysis session:
1. In the Visual Analysis window, click
> New on the toolbar.
2. In the Select Business View dialog, select the required one and click OK.
3. A new Visual Analysis window will be loaded.
To start a Visual Analysis session on a saved visual analysis template during a Visual Analysis session:
1. In the Visual Analysis window, click
2. The Open dialog will be displayed.
> open or the Open button
on the toolbar.
3. In the Open In section, browse to the folder where the visual analysis template is located in the server resource tree.
The folder may be Public Reports or My Reports. You can use the button
to return to the parent folder.
4. Select the visual analysis template in the resource table which lists all the visual analysis templates in the current
directory. Click the column names to change the order of the visual analysis templates in the table list if required.
5. The File Name box shows the name of the selected visual analysis template.
6. Click OK. The visual analysis template will be loaded into a new Visual Analysis window.
Accessing Visual Analysis via URL
All the parameters are encapsulated as JSON (JavaScript Object Notation) objects. It will help if you
obtain some knowledge on JSON to understand the syntax more clearly.
Definition
ResourceDef: {
"name":"/SampleReports/myVA.va", // Required. The resource file name with its full path. The path
could be a disk path or a server resource tree path. For the latter, it could be either in the My Reports
folder (/USERFOLDERPATH/admin/) or in the Public Reports folder (/).
"ver":" -1", // Optional. The version number of the resource.
"real":"false" // Optional. Value: true/false. true means the resource path is a real disk path and false
means a server resource tree path. When it is a real path, "real":"true" must be specified.
}
// catDef: It's a ResourceDef object to describe a catalog resource.
ResourceDef catDef = {name:"/SampleReports/Sampl.cat"}
jrd_catalog=$catDef
jrd_catalog={
"name":"xxx", // Required. The full path of the catalog.
"ver":"-1", // Optional.
"real":"false" // Optional.
}
// vaDef: It's a ResourceDef object to describe a Visual Analysis resource.
ResourceDef vaDef = {name:"/SampleReports/VisualComponent 1.va"}
jrd_vcres=$vaDef
jrd_vcres={
"name":"xxx", // Required. The full path of the Visual Analysis resource.
"ver":"-1", // Optional.
"real":"false" // Optional.
}
DataSource: {
"catalog":"$catDef", // Catalog.
"ds:"Data Source 1", // Data source name.
"query":"Query1", // Query name.
"bv":"WorldWideSalesBV" // Business view name.
}
// dsDef: It's a DataSource object to describe a Visual Analysis data source.
jrd_datasource=$dsDef
jrd_datasource={
"catalog":"$catDef", // Catalog.
"ds:"Data Source 1", // Data source name.
"query":"Query1", // Query name.
"bv":"WorldWideSalesBV" // Business view name.
}
For the usage of jrd_resext, refer to Running dashboards via URL.
Examples for creating a new Visual Analysis session
●
Create a new session with specified business view information. The data source selection panel will
not pop up.
http://localhost:8888/webos/app/designer/run.jsp?jrd_datasource=$dsDef
http://localhost:8888/webos/app/designer/run.jsp?jrd_datasource={"catalog":{"name":"/
SampleReports/SampleReports.cat"},"ds":"Data Source
1","query":"WorldWideSales","bv":"WorldWideSalesBV"}
●
Create a new session with specified catalog. This entry will pop data source panel and only include
business views which belong to the specified catalog.
http://localhost:8888/webos/app/designer/run.jsp?jrd_catalog=$catDef
http://localhost:8888/webos/app/designer/run.jsp?jrd_catalog={"name":"/SampleReports/
SampleReports.cat","ver":"-1","real":"false"}
●
Create a new session with specified catalog path. This entry will pop data source panel and include
all catalogs and business views in them which are under the specified catalog path and it sub folders.
http://localhost:8888/webos/app/designer/run.jsp?jrd_catpath={"name":"/
SampleReports"}
●
Create a new session without any data source information:
http://localhost:8888/webos/app/designer/run.jsp
It is equal to the following:
http://localhost:8888/webos/app/designer/run.jsp?jrd_catpath={"name":"/"}
Examples for opening an existing Visual Analysis template
●
●
http://localhost:8888/webos/app/designer/run.jsp?jrd_vcres=$vaDef
http://localhost:8888/webos/app/designer/run.jsp?jrd_resext={"reslst":[{"name":"/
SampleReports/VisualComponent 1.va",ver:-1,real:false}],active:0}
Performing visual analysis
After you access the Visual Analysis interface in your browser by any of the ways introduced in Starting Visual Analysis session, you can make use of the
tool to analyze the data in a business view intuitively and conveniently.
The following are operations you can make use of in order to interact with data. Note that only group and aggregation fields can be added into the data
presentation area.
Adding data fields as column or row headers
Group and aggregation fields can be added as column or row headers. Drag a data field from the Resources panel and drop it to the proper control box,
beside the four control boxes allows you to select a
following the instructions of the four control boxes highlighted in the below image. The button
group or an aggregation field from the drop-down list instead of dragging the object from the resource panel.
When an aggregation is added as a header, the aggregation will be used to draw axes in the header cells.
Multiple fields can be added as column or row headers. For column headers, the order of the group fields or the aggregation fields from left to right decides
the grouping order from the first level to the last level. That is, the grouping order is from left to right. For example, there are Year, Region, and Category
group fields added as the column headers and are displayed from left to right. Year will be the first level group, Region the second, and Category the last.
For row headers, the grouping order is from bottom to top.
When you drag a field to be a header, you can decide its position if there are already existing fields, or if you are not satisfied with the current grouping
order, you can adjust the fields' order by dragging and dropping.
To remove a data field from being a column or row header, drag the field outside of its control box.
Changing the display type of the data values
To specify the way of presenting the data values, click the Display Type button which may vary with the context and select the required display type from
the drop-down list.
Showing the tip information of the data values
Put the mouse pointer on any date value in the date presentation area, and a tip box will be displayed showing the detailed information of the value.
Identifying the members of a data field by colors
For example, to mark different regions with different colors, drag the Region field to the Color button
in the legend section. See Color legend for more.
Identifying the members of a data field by sizes
For example, to mark total quantity by size, drag the Total Quantity field to the Size button
in the legend section. See Size legend for more.
Showing the labels of the members of a data field
For example, to show the country names in the data values displayed in the data presentation area, drag the Country field to the button
section. See Label legend for more.
in the legend
Dividing pie into sections by an aggregation field
When the display type is Pie, you can make the pie divided around the center according to an aggregation field. For example, to divide the pie by total
sales, drag the Total Sales field to the Slice button
in the legend section. See Slice legend for more.
Identifying the members of a data field by shapes
When the display type is Shape, to mark different product categories with different shapes, drag the Category field to the Shape button
section. See Shape legend for more.
in the legend
Exchanging columns and rows
To exchange the positions of the columns and rows, click the Swap button
on the toolbar.
Filtering data
Filters can be created on group fields but not on aggregations. Multiple filters are supported.
To create a filter based on a group field, take either of the ways:
●
Drag a group field from the Resources panel into the Filters panel.
●
In the data presentation area, click a group field and select Use as Filter from the drop-down menu.
A filter will be created with all the values of the group field being applied. Then specify the desired values in the filter and the data values in the data
presentation area will be filtered.
To remove a filter, drag its field outside of the Filters panel.
To remove all the filters from the Filters panel, click the Menu button
Filters on the Filters panel title bar.
on the toolbar and then select Clear Filters. Or make use of the Clear All
Move the mouse cursor on the Filters panel title bar and you will see an arrow button
●
●
Reset All Filters
Resets the values of all the filters to the initial state.
Clear All Filters
Removes all the filters from the Filters panel.
Move the mouse cursor on a filter's title bar and you will see more filter options:
on the right. Click the arrow and there are two options:
●
●
●
Reset
Resets the values of the filter to the initial state.
Reverse
Reverses the values of the filter.
More Options
Changes the display type of the filter:
❍
❍
❍
❍
Checkbox
The field values are displayed with checkboxes and multiple values can be selected.
Radio
The field values are displayed with radio buttons and only one single value can be selected except for all values.
Range Slider
The field values are displayed with a slider and a range of values can be selected.
Slider
The field values are displayed with a slider and only one single value can be selected except for all values.
Undoing/Redoing actions
You can undo or redo some actions. To do this, click the Undo button
or Redo button
on the toolbar.
Refreshing the current data view
Click the Refresh button
on the toolbar.
Switching fields between legends
Within a display type, after a field is bound with a legend type, you can directly drag the field to another legend type, or use the context menu after you
click the field name bar under the original legend.
Showing/Hiding the row/column title/header
To show or hide the row/column title or header, click a related row/header control box and then select or unselect Show Title or Show Header on the
drop-down menu.
Switching the view mode
To switch the view mode, click the Menu button
down list on the toolbar.
on the toolbar and then select an item on the View list. Or select an item from the view mode drop-
There are also some quick ways to switch between the modes:
●
Under the Normal View mode, double-click any position in the data area, the view mode will be switched to Fit Visible.
●
Under the Fit XXX mode, double-click any position in the data area, the view mode will be switched to Normal View.
The view mode status will not be saved when saving the visual analysis template.
Examples
The following examples use the WorldWideSalesBV in /SampleReports as the business view.
●
Example 1: Displaying the data values in text
●
Example 2: Displaying the data values as bar
●
Example 3: Displaying the data values as line
●
Example 4: Displaying the data values as pie
●
Example 5: Displaying the data values as shape
Example 1: Displaying the data values in text
1. Make sure you do not change the display type, which is Text by default.
2. To view total sales, drag Total Sales from the Resources panel and drop it to the Label button
in the legend section.
There is only one value in the data presentation area which is the total sales in the whole business view.
3. Now let's view total sales in different years. Drag Sales Year to the column control box
.
4. To add product category as the row header, drag Category to the row control box
5. Drag Region as a column header right to Sales Year.
.
Then get the following:
6. We will move Sales Year from the column header to row header by dragging.
7. We will filter the data with product type. Drag Product Type from the Resources panel to the Filters panel. Then deselect Regular.
8. Only the data about Decaf will be displayed.
Example 2: Displaying the data values as bar
1. Click the Display Type button
and then select Bar
2. Drag Sales Year to the row control box
draw axes in the row header.
from the drop-down list.
and Total Sales to the row control box
. The Total Sales field is used to
3. To mark different regions by color, drag Region to the Color button
in the legend section.
4. Drag Category to the column control box
as the column header.
5. To show the total cost in each region by size, drag Total Cost to the Size button
in the legend section.
Example 3: Displaying the data values as line
1. Click the Display Type button
and then select Line
2. Drag Total Sales to the row control box
demonstrate the sales trend along the quarters.
from the drop-down list.
as the axis and Sales Quarter to the column control box
to
3. To view the sales trend along the quarters in each region, drag Region to the Color button
in the legend section.
Example 4: Displaying the data values as pie
1. Click the Display Type button
and then select Pie
from the drop-down list.
2. To mark different regions in different color in the pie, drag Region to the Color button
in the legend section.
3. To demonstrate the total sales of each region by portion in the pie, drag the field Total Sales to the Slice button
4. To view the total sales in different years, drag the field Sales Year to the column control box
in the legend section.
.
Example 5: Displaying the data values as shape
1. Click the Display Type button
and then select Shape
from the drop-down list.
2. Add Category as the column header and Total Sales as the row axis.
3. To mark different regions with different shapes, drag Region to the Shape button
in the legend section.
4. To change the shape pattern, click the Shape button
. Then in the Edit Shapes dialog, select Pattern3 from the drop-down list and click OK.
5. To distinguish the shapes by color, drag Region to the Color button
in the legend section.
Saving visual analysis templates
Visual analysis templates can be saved into the My Reports and Public Reports folders, and therefore you can go to the
two folders to open them directly. Also, you can delete analysis templates there.
To save the changes you made during the visual analysis session, click the Save button
on the toolbar.
If the visual analysis template is newly created and has not yet been saved, the Save As dialog will be displayed.
1. In the Save In section, browse to the folder where you want to save the analysis template in the server resource
tree. The folder may be Public Reports or My Reports. You can use the button
The root folder cannot be used to store resources into.
to return to the parent folder.
The resource table shows the analysis templates in the current directory. Click the column names to change the
order of the analysis templates in the table list if required.
2. In the File Name box, enter the name of the analysis template or use the default name, without suffix.
3. Click OK to save the analysis template. The saved template is linked to its original catalog.
To save a copy of a visual analysis template, click
dialog, and then do as above.
on the toolbar or click
> Save As to show the Save As
After saving your analysis template into the server resource tree, you can browse to its directory on the JReport Console
> Resources page and run it directly.
To find a newly saved visual analysis template version, browse to locate the row that the visual analysis template is in
on the JReport Console > Resources page, put the mouse pointer over the row and click the Version command button
on the floating toolbar, the Analysis Versions panel will be displayed showing the versions.
Note: You will not be able to save resources to some locations if you do not have Write permission.
Integrating JReport Server with a Java
Application Server
JReport Server is implemented using Java Servlet technology and Java Server Pages (JSP). These
servlets and JSP pages enable you to work with any Java EE compliant application server and
administer JReport Server remotely through a web browser.
In order to deploy to an application server, you first have to create a Web Application Archive (WAR)
file or an Enterprise Application Archive (EAR) file to include a JReport Server, and then use the
application server deployment tools to deploy the WAR/EAR file.
This chapter covers the following:
●
Seamless integrated security solution
●
Building a WAR/EAR file to include a self-contained JReport Server
●
Deploying JReport Server to a Java application server
●
Integrating remote JReport Server
Note: Page Report Studio and Web Report Studio slather dynamic classes, so you probably encounter
"OutOfMemoryError: PermGen space" problem when working with them after integration. To solve the
problem, you need to add -XX:MaxPermSize=256m to JVM or set the number to a bigger one according
to your case.
Seamless integrated security solution
As a reporting server, JReport Server protects information via authentication and authorization
processes. Furthermore, JReport allows a web application to embed this reporting solution in it
seamlessly not only on UI but also with the Java EE technology. In this way, the seamless integrated
security solution becomes one of the key solutions of JReport Server.
There are all kinds of scenarios on using JReport solution. However, they can all be categorized into the
following two types according to the location of the JReport Server instance.
JReport Server instance is located in the same JVM as the web
application
In this scenario, the application includes JReport Server JAR files into the same JVM, and it also
includes JReport built-in servlets and JSPs which handle running web and page reports and other
reporting services, for example, scheduling reports.
Description of the illustration
In this scenario, the client (HTTP client) most of time will send a request to the portal, JSP or Servlet of
the web application, and the web application can either call the public Server API to the server instance
directly to run a report and output a report result to file system, or it can re-direct the request to the
JReport services provided by the JReport JSPs and Servlets, for example the Page Report Studio JSP
and Servlet. JReport JSPs/Servlets will first make sure the request is authenticated and authorized.
After which, it will call the internal API method against the JReport Server Instance in the same JVM to
fulfill the requirement and return suitable information to the client via JSPs or internally generated
output steam.
In the illustration above, you can see that the HTTP client can send a request directly to the application
JSP/Servlets or JReport JSPs/Servlets. Before a response is made by the JReport JSP and Servlet, an
Auth Check is performed to authenticate the session and then authorize the action. Normally, the builtin authenticator and authorization instance of JReport Server (Instance) is called to perform these
checking actions. However, if the application wants to control the process, the web application
developer can set up the configuration to ensure that the customized authenticator and authorization
instance is used instead.
Pay attention to the RED box: External Authorized instance. This Java class implements JReport jet.
server.api.http.HttpExternalAuthorized to provide the authenticated user ID from the session. If this
Instance returns a user ID, JReport will pass it to its authenticator to check if it is valid. If the user ID
is valid for JReport, JReport will qualify the session of the request, and will not ask for a login again. If
this external authorized instance does not return a user ID, JReport will respond the request by asking
for a login.
The other RED box - Authenticator and Authorizer instance, can be provided by implementing two other
interfaces:
jet.server.api.custom.security.AuthenticationProvider and jet.server.api.custom.security.
AuthorizationProvider.
The AuthenticationProvider is used to authenticate the user ID, including whether or not the user ID is
valid. The AuthorizationProvider is used to check the privileges of the user against the action that the
user requests.
During the auth check process, if the external authorized instance returns a user ID of the session,
JReport auth check will continue to send the user ID to the AuthenticatorProvider to check if it is valid
or not. If the user is valid, the auth check will qualify the session of the request, and then continue to
check if the action is valid for the user by asking the AuthorizationProvider instance.
In general, there is an authentication callback via the implemented interface of External Authorized.
Two security check providers can be implemented to seamlessly integrate JReport security into the
application.
JReport Server instance is located in a different JVM from the
web application
From the web application itself, the architecture is not changed. However, the way that it uses the
JReport solution is different since the JReport Server Instance is outside of the Web application server.
Inside of the Web Application, the instance is RMI server being called by the web application server or
JReport built-in JSP/Servlets for the RMI solution.
Building a WAR/EAR file to include a self-contained
JReport Server
There are two ways of creating a WAR or EAR to include a self-contained JReport Server:
●
●
Create a WAR/EAR file using the provided tool makewar.bat/makewar.sh after you have installed a
JReport Server. If you are not familiar with JReport Server, it is better to use this way.
Create a WAR manually. The method is no longer needed but is still available in this release in case
you would like to take it.
The self-contained JReport Server is based on a library. The library contains all class packages required
by the JReport Server runtime, such as jrenv.jar, JRESServlets.jar, JREngine.jar, and JRWebDesign.jar.
In the library, jrenv.jar contains the entire JReport runtime environment, and is the key to the selfcontained integration solution. With the self-contained solution, you do not have to specify the JReport
Server installation root as the reporthome.
When you create a JReport Server WAR/EAR file using the provided tool, the jrenv.jar package will be
automatically put into the WAR/EAR, and will be extracted to the specified reporthome when initializing
JReport Server.
The following is the structure of the jrenv.jar package:
jrenv.jar
workspace/ -- This is the root folder.
bin/ -- This folder contains the license file jslc.dat and configuration files, such as
LogConfig.properties and redirect.properties.
lib/ -- This folder contains jar files needed by applets, such as view12.jar and chart.jar.
template/ -- This folder contains template files.
profiling/report/ -- This folder contains profiling report files.
jreports/ -- This folder contains demo reports or pre-published reports.
db/ -- This folder contains demo database for demo reports.
help/ -- This folder contains help documents.
The bin/, lib/, and template/ folders are necessary for the JReport runtime, while the profiling/,
jreports/, db/ and help/ folders are optional.
Note: There is a parameter in self-contained WAR/EAR - autoDetectServletPath. It is used to
dynamically detect and modify servlet path based on context path of self-contained WAR/EAR when
deploying the WAR/EAR to a J2EE application server. This property is enabled by default, and the actual
servlet path will be concatenating "context path" with "default servlet path" set in server.properties. If
you do not want this way, you can disable the feature using either of the following ways:
●
●
Before making your WAR/EAR, set the parameter autoDetectServletPath to false in makewar.xml
which is located in <install_root>\bin.
If the WAR/EAR has already been built, go to web.xml, set this parameter autoDetectServletPath to
false.
The following are topics covered in the section:
●
Building a JReport Server WAR/EAR by tool
●
Building a JReport Server WAR manually (deprecated)
●
Four ways of integrating JReport Server
Building a JReport Server WAR/EAR by tool
A tool based on the Apache Ant project is provided by JReport Server to build JReport Server WAR/EAR
files which contain the full JReport Server runtime environment. The WAR/EAR files can be deployed to
any Java EE compliant application server without having to specify a JReport Server installation root as
the reporthome.
You can use the default settings to generate a JReport Server WAR/EAR, or you can customize the
reporthome and data source for JReport Server before generating the WAR/EAR using the provided tool.
●
Creating a JReport Server WAR/EAR
●
Specifying reporthome for JReport Server in a Java EE environment
●
Specifying a data source for JReport Server in a Java EE environment
Creating a JReport Server WAR/EAR
JReport Server provides a tool for building a WAR or EAR file. The tool is makewar.bat/makewar.sh,
and makewar.xml in <install_root>\bin.
makewar.xml
This file can be used to specify the following:
●
Targets specified to build the WAR/EAR file. They start with the tag <target name="xxx"...>. You
can modify the target names. By default, the main targets in the makewar.xml are as follows:
❍
Making the server runtime environment
❍
Making the WAR file for normal or remote integration
❍
Making the EAR file
Temp directories.
●
❍
❍
●
The temp directory used to save the temp files when building the WAR/EAR. By default, it is
<install_root>\bin\distribute\temp.
The directory which is used to store the generated WAR/EAR file. By default, it is <install_root>
\bin\distribute.
The deployment descriptors, such as web.xml and application.xml. The configuration information,
such as the database connection information for the WAR/EAR file is stored in these files.
makewar.bat/makewar.sh
The batch/script file used to build a JReport Server WAR/EAR according to the target specified in
makewar.xml.
Usage
makewar.bat/makewar.sh [Target Name] [-Dpredeploy=ReportFolder] [-Dreporthome=XXX] [Djrs.remote.host=XXX] [-Djrs.remote.rmiport=XXX] [-Djrs.rmi.auth_file=XXX]
Options
●
●
Target Name
The following targets can be performed:
❍
buildWar - Specifies to build the JReport Server WAR. It is the default target.
❍
buildEar - Specifies to build the JReport Server EAR.
❍
buildRemoteWar - Specifies to build the JReport Server WAR for remote integration.
-Dpredeploy=ReportFolder
Allows you to deploy the reports and catalogs under ReportFolder to the WAR/EAR file.
●
●
●
●
-Dreporthome
Specifies the reporthome that will be set into web.xml in the WAR/EAR. If this argument is not set,
reporthome will be decided when the WAR/EAR is loaded by the application server and the location
will be %user.home%/.jreport/default. This argument takes effect only when the target name is
buildWar, buildEar, or buildWar4WS.
-Djrs.remote.host
Specifies the server's RMI host when building a WAR for remote integration. This argument takes
effect only when the target name is buildRemoteWar.
-Djrs.remote.rmiport
Specifies the server's RMI port when building a WAR for remote integration. This argument takes
effect only when the target name is buildRemoteWar.
-Djrs.rmi.auth_file
Specifies the RMI auth file with the absolute file path when building a WAR for remote integration.
This argument takes effect only when the target name is buildRemoteWar.
Examples
●
Builds the JReport Server WAR file which is defined by makewar.xml (the default target). The
generated WAR file is saved to the default directory <install_root>\bin\distribute.
makewar.bat
●
Builds the JReport Server WAR file, and saves the generated WAR file jreport.war to the default
directory <install_root>\bin\distribute. When deploying the jreport.war to an application
server, the report home will use C:\JReport.
makewar.bat buildWar -Dreporthome=C:\JReport
●
Builds the JReport Server EAR file, and saves the generated EAR file jreport.ear to the default
directory <install_root>\bin\distribute.
makewar.bat buildEar
●
Builds the JReport Server WAR file, and deploys the reports and catalogs in C:\myReport to the WAR
file. The generated WAR file jreport.war will be saved in the default directory <install_root>\bin
\distribute.
makewar.bat buildWar -Dpredeploy=c:\myReport
●
Builds the JReport Server WAR file as defined by makewar.xml for remote integration. The generated
WAR file is saved to the default directory <install_root>\bin\distribute.
makewar.bat buildRemoteWar -Djrs.remote.host=127.0.0.1 -Djrs.remote.rmiport=1129 Djrs.rmi.auth_file=C:\JReport\Server\bin\rmi.auth
Specifying reporthome for JReport Server in a Java EE environment
JReport Server requires a reporthome as its working space to hold the entire JReport runtime
environment, including the server properties, configuration files and resources. The package jrenv.jar
that contains the entire JReport runtime environment will be extracted to the specified reporthome
when initializing JReport Server. The reporthome can be any location on the disk where JReport Server
has read and write privileges.
You do not have to specify a reporthome for JReport Server since it will create a default reporthome
location <user.home>/.jreport/default.
However, JReport Server enables you to customize the reporthome location before creating the JReport
Server WAR/EAR using the provided tool. You can either specify reporthome directly or specify the
implementation of the jet.server.api.http.CustomizedServerEnv interface.
Note: Make sure that the reporthome for the integrated JReport Server is different from that of the
standalone JReport Server.
Interface CustomizedServerEnv
The jet.server.api.http.CustomizedServerEnv interface can be used for specifying the JReport Server
reporthome and for setting the server properties in a Java EE environment. It contains two methods:
●
String getReportHome()
●
Properties getServerProperties()
If you specify the implementation of this interface, JReport Server will obtain not only reporthome but
also server properties.
Three ways of specifying reporthome
There are three ways of specifying reporthome directly or the implementation of the jet.server.api.http.
CustomizedServerEnv interface:
●
By JVM -D parameter.
Set the JVM option -Dreporthome before starting the application server, for example:
-Dreporthome=/home/jreport
●
Invoking the method jet.server.api.http.HttpUtil.initEnv(Properties props).
For example:
Properties props = new Properties();
props.setProperty("reporthome", "/home/test/JReport");
HttpUti.initEnv(props);
●
Using ejb-jar.xml/web.xml.
The following introduces several methods of specifying reporthome or implementation of
CustomizedServerEnv:
●
Using the default reporthome
●
Specifying reporthome directly in web.xml or ejb-jar.xml
●
Using the default implementations of jet.server.api.http.CustomizedServerEnv
●
Using a customized implementation of jet.server.api.http.CustomizedServerEnv
Using the default reporthome
If you do not specify a reporthome, the self-contained JReport Server will create a default working
folder. The default working folder is <user.home>/.jreport/default, where <user.home> is the system
property user.home retrieved from Java VM. The JReport Server has the Read and Write privileges in
this directory. Different OSs have different real paths for <user.home>. For example,
For Windows: C:\Documents and Settings\username
For Unix/Linux: /home/username
Notes:
●
●
●
user.home is a system property of the Java VM (-Duser.home=xxx). So you can also specify different
folders for this JVM option.
If JReport Server is running on Windows as a service, the username is the user who installed the
service or the specified logon user for the service.
If JReport Server is running as a Unix/Linux Daemon, you can specify the JVM system property Duser.home in the script file that starts JReport Server.
Specifying reporthome directly in web.xml or ejb-jar.xml
It is recommended that you use the <env-entry></env-entry> tags to specify the reporthome directly
in the target "web.xml.norpthome" in the makewar.xml file or in ejb-jar.xml. Also, in the target "web.
xml.filter", you can specify the reporthome using the <context-param></context-param> tags.
Specifying the reporthome for WAR
You can use one of the two methods listed below to specify the reporthome for WAR:
●
In the makewar.xml file, use the <env-entry></env-entry> tags to specify the reporthome in the
target "web.xml.norpthome", and then uncommented the setting. For example:
<env-entry-name>jreport.rpthome</env-entry-name>
<env-entry-value>/home/jreport</env-entry-value>
<env-entry-type>java.lang.String</env-entry-type>
This is the recommended way to set reporthome since the <env-entry></env-entry> tags are also
supported in ejb-jar.xml (if you call the Server API in your EJB).
●
In the makewar.xml file, use the <context-param></context-param> tags to specify the
reporthome in the target "web.xml.filter", for example:
<context-param>
<param-name>reporthome</param-name>
<param-value>/home/jreport</param-value>
</context-param>
Specifying the reporthome for EAR
The same methods can be used to specify the reporthome of building the EAR file as of building the
WAR file. However, because you can wrap WAR and EJB in the EAR file, you should ensure that you put
the reporthome information either in the target "web.xml.norpthome" in the makewar.xml file (for the
web module) or in ejb-jar.xml (for the EJB module).
In ejb-jar.xml, use the <env-entry></env-entry> tags to specify the reporthome. For example,
<env-entry>
<env-entry-name>jreport.rpthome</env-entry-name>
<env-entry-value>/home/jreport</env-entry-value>
<env-entry-type>java.lang.String</env-entry-type>
<env-entry>
Using the default implementations of jet.server.api.http.CustomizedServerEnv
The self-contained JReport Server provides two implementations of CustomizedServerEnv. They are jet.
server.DefaultServerEnv and jet.server.MultipleInstanceServerEnv.
jet.server.DefaultServerEnv
If you use this implementation, you will not need to specify it in the target "web.xml" in the makewar.
xml or in ejb-jar.xml, since it can find the customized reporthome from the <context-param></
context-param> tags of the target "web.xml" or the <env-entry></env-entry> tags of web.xml or ejbjar.xml.
jet.server.MultipleInstanceServerEnv
This implementation is extended from DefaultServerEnv. It enables finding the reporthome not only
from <context-param></context-param> or <env-entry></env-entry> tags, but also from an
external file <user.home>/.jreportrc. However, this implementation has three main limitations. They
are:
●
●
This implementation must be clearly specified with the <env-entry></env-entry> tags in the target
"web.xml" in the makewar.xml or in ejb-jar.xml, as follows:
<env-entry>
<env-entry-name>jreport.servenv</env-entry-name>
<env-entry-value>jet.server.MultipleInstanceServerEnv</env-entry-value>
<env-entry-type>java.lang.String</env-entry-type>
</env-entry>
The JReport Server must be initialized with JRServerContextListener from a Web module.
Since in cases of deploying multiple JReport Server instances in one Java EE application server
without touching the WAR, such as extracting the WAR, setting reporthome and rebuilding the WAR,
JReport Server has to use ServletContext to generate an ID for every instance. JReport Server
retrieves javax.servlet.context.tempdir from ServletContext by invoking the getAttribute(String)
method, and then uses this value to generate the instance ID.
For detailed information, see Java Servlet Specification Version 2.3/2.4 SRV.3.7.1 Temporary
Working Directories.
●
The <user.home>/.jreportrc file must be created by JReport Server. You can only edit the file to
change the reporthome after the JReport Server initialization.
Since the instance ID is generated based on a hash code retrieved from javax.servlet.context.
tempdir, it cannot be pre-assigned, and is therefore impossible for you to create the <user.home>/.
jreportrc file. However, once the file has been created, you can edit it to change the reporthome for
each instance. The RC file can hold multiple records. The record format should be as follows:
jreport.rpthome.<instanceID>=the-instance-report-home
The instanceID is created by JReport Server during its first initializing. It is a string of HEX encoded
hash value. For example:
jreport.rpthome.12345678=/home/user1/.jreport/instance.12345678
jreport.rpthome.12345abc=/home/user1/.jreport/instance.12345abc
If JReport Server cannot get the reporthome from CustomizedServerEnv, it will create a default
reporthome in <user.home>/.jreport/default.
The following is an example of specifying reporthomes when deploying multiple server instances using
jet.server.MultipleInstanceServerEnv:
Example: Specifying reporthomes when deploying multiple server instances
JReport Server provides an internally implemented class of the jet.server.api.http.
CustomizedServerEnv interface - jet.server.MultipleInstanceServerEnv which supports multiple JReport
Server instances in one Java EE application server. The reporthome of each instance can be assigned
by the class automatically. To do this, follow the steps below:
1. In the file makewar.xml, use the <env-entry></env-entry> tags to specify jet.server.
MultipleInstanceServerEnv in the target "web.xml". For example:
<env-entry>
<env-entry-name>jreport.servenv</env-entry-name>
<env-entry-value>jet.server.MultipleInstanceServerEnv</env-entry-value>
<env-entry-type>java.lang.String</env-entry-type>
</env-entry>
2. Since different JReport instances cannot access the same JReport Server system database at the
same time, you will need to create a dbconfig.xml file to store the connection information, and put
it in jrenv.jar in workspace\bin (you can find the jrenv.jar file after extracting jreport.war) for
each JReport Server WAR/EAR.
For detailed information about modifying the dbconfig.xml, see Configuring the server database.
3. When the JReport Server WAR/EAR has been deployed, JReport will create a file .jreportrc in
<user.home>, and each JReport instance will read its reporthome from this file. This file must be
created by JReport Server, however, you can edit it in order to change the reporthome after it has
been created.
Using a customized implementation of jet.server.api.http.CustomizedServerEnv
You can implement the interface and add your class to the generated WAR/EAR file, then use the <enventry></env-entry> tags to specify your implemented class in the target "web.xml" in the makewar.xml file
or in ejb-jar.xml.
The following is an example of specifying a customized implementation of CustomizedServerEnv in the target
web.xml in the makewar.xml file or in ejb-jar.xml using the <env-entry></env-entry> tags. Here the
customized implementation of CustomizedServerEnv is named my.JReportServerEnv.
<!-- JReport Server calls my.JReportServerEnv to obtain reporthome and server properties.-->
<env-entry>
<env-entry-name>jreport.servenv</env-entry-name> <!-- must be jreport.servenv-->
<env-entry-value>my.JReportServerEnv</env-entry-value> <!-- your class name -->
<env-entry-type>java.lang.String</env-entry-type>
</env-entry>
Notes:
●
●
JReport Server will retrieve the reporthome and properties from your implemented class when the WAR/EAR
file has been deployed.
The properties returned from getServerProperties() can be the properties listed in server.properties file in
the directory <install_root>\bin, JVM System properties, or self-defined ones.
Specifying a data source for JReport Server in a Java EE environment
See Configuring the server database when integrating with an application server for detailed
information.
Building a JReport Server WAR manually (deprecated)
This section introduces a method that has been used in earlier versions. If using this method, you will have to
specify the JReport Server installation root as the reporthome unless you make the WAR be a self-contained
solution.
This section takes creating a WAR file on Unix for example. The instruction is applicable to both Unix and
Windows platforms. However, the paths for Windows should use the Windows format, for example, C:
\JReport\Server, while paths for Unix should use the Unix format, for example, /opt/JReport/Server.
It is assumed that JReport Server has been installed to /opt/JReport/Server.
Take the following steps to build a JReport Server WAR manually:
1. Create a new directory jreport in the JReport Server installation root: /opt/JReport/Server/jreport.
2. Create a sub directory WEB-INF in jreport: /opt/JReport/Server/jreport/WEB-INF.
3. Create a web.xml file in the WEB-INF directory as follows:
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems,
Inc.//DTD Web Application 2.3//EN"
"http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app>
<listener>
<listener-class>jet.server.servlets.JRServerContextListener</listener-class>
</listener>
<servlet>
<servlet-name>jrserver</servlet-name>
<servlet-class>jet.server.servlets.JRServlet</servlet-class>
</servlet>
<servlet>
<servlet-name>sendfile</servlet-name>
<servlet-class>jet.server.servlets.SendFileServlet</servlet-class>
</servlet>
<servlet>
<servlet-name>dhtml</servlet-name>
<servlet-class>jet.web.dhtml.DHTMLlet</servlet-class>
</servlet>
<servlet>
<servlet-name>help</servlet-name>
<servlet-class>jet.web.dhtml.JHelplet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>jrserver</servlet-name>
<url-pattern>/jrserver/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>sendfile</servlet-name>
<url-pattern>/sendfile/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>dhtml</servlet-name>
<url-pattern>/dhtml/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>help</servlet-name>
<url-pattern>/help/*</url-pattern>
</servlet-mapping>
</web-app>
4. Create a directory lib in the jreport/WEB-INF directory:
mkdir lib
5. Create a directory pages in the jreport/WEB-INF/lib directory:
mkdir lib/pages
6. Copy all of the files in /opt/JReport/Server/lib/pages to the jreport/WEB-INF/lib/pages directory:
cp /opt/JReport/Server/lib/pages/* lib/pages
7. Create a jar file to include the resources folder which is located in /opt/JReport/Server and name it
languages.jar. For example, run the following command:
jar -cvf languages.jar resources
Then put the languages.jar in /opt/JReport/Server/lib.
8. Copy the following jar files from /opt/JReport/Server/lib to the jreport/WEB-INF/lib directory:
commons-codec-1.2.jar, jai_codec.jar, jai_core.jar, JREngine.jar, JRESServlets.jar, JRWebDesign.jar,
languages.jar, log4j-1.2.8.jar, sac.jar, tar.jar, xercesImpl.jar, xml-apis.jar.
If you want to export reports to the following formats, you should copy the corresponding jar to the
jreport/WEB-INF/lib directory:
❍
To e-mail or use the e-mail Notification function, copy activation-1.1.jar and mail-1.4.jar.
❍
To FTP, copy commons-net-ftp-2.0.0.jar.
❍
To PDF and Page Report Result, copy itext_1.5.4.jar.
❍
To Excel, copy poiHSSF_151.jar.
9. Copy the index.htm file and the admin, dhtmljsp, images, javascript, jinfonet, skin, and style folders
from /opt/JReport/Server/public_html to the /opt/JReport/Server/jreport directory:
cp -r /opt/JReport/Server/public_html/* /opt/JReport/Server/jreport
Notes:
❍
❍
The jsp files within the admin folder are used by the JReport Administration pages. Those within the
dhtmljsp folder are used when viewing reports in Page Report Studio.
If you copy index.htm and these folders mentioned above to a sub folder in /opt/JReport/Server/
jreport, for example, /opt/JReport/Server/jreport/sub, to view reports in Page Report Studio,
you need:
■
Modify the server.properties file:
web.skin.dir=/jreport/sub/skin
■
Uncomment the following lines in dhtml.jsp in the dhtmljsp folder and make it adapt to the
environment as follows:
dhtmlConfig.setDHTMLContextPath(SessionID,"http://localhost:8080/jreport/sub");
dhtmlConfig.setDHTMLJspUrl(SessionID,"/jreport/sub/dhtmljsp/");
dhtmlConfig.setDHTMLServletUrl(SessionID, RptSetId, "/jreport/dhtml");
■
In the step 10, edit the index.htm file like this:
<FRAME name="ind" src="/jreport/sub/jinfonet/index.jsp" frameborder="0">
Then go to step 11.
10. Edit the index.htm file and add the context path /jreport to the src tag. Note that the path separator
character is the Unix style "/" when referencing JSP. The result should be as follows:
<FRAME name="ind" src="/jreport/jinfonet/index.jsp" frameborder="0">
11. If you are going to create the war for use in Weblogic, you need to check whether there is a weblogic.
xml in the jreport/WEB-INF directory. If yes, make sure the following line is added in the weblogic.xml:
<show-archived-real-path-enabled>true</show-archived-real-path-enabled>
If no, create a weblogic.xml and add it in the jreport/WEB-INF directory. The content in the weblogic.
xml looks like:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE
weblogic-web-app PUBLIC "-//BEA Systems, Inc.//DTD Web Application 8.1//EN"
"http://www.bea.com/servers/wls810/dtd/weblogic810-web-jar.dtd">
<weblogic-web-app>
<container-descriptor>
<show-archived-real-path-enabled>true</show-archived-real-path-enabled>
</container-descriptor>
</weblogic-web-app>
12. Using the following command to create a WAR file named jreport.war:
jar -cvf jreport.war index.htm admin dhtmljsp images javascript jinfonet skin style WEBINF
Note: The jar utility is in the Java home bin directory. If it is not on your path you must call jar with the
entire path, for example, /opt/jdk1.6.0_17/bin/jar.exe.
To make the WAR be a self-contained solution
To make the WAR include a self-contained JReport Server, except for the above procedure, you need create
jrenv.jar and then put it in the jreport/WEB-INF/lib directory before creating the WAR.
Use either way to create the jrenv.jar:
●
By the makewar.bat/makewar.sh tool
For example: run the command makewar jrenv.jar
●
Creating manually
Make sure all necessary contents are included and then use a proper tool to package them into a jar file.
See also Building a WAR/EAR file to include a self-contained JReport Server for details about the structure of
the jrenv.jar.
Four ways of integrating JReport Server
You can either create a JReport Server WAR/EAR, or create your WAR/EAR and embed a self-contained
JReport Server inside it. The following are four ways of building a WAR/EAR file in order to include a
self-contained JReport Server:
●
Integrating by building a JReport Server WAR
●
Integrating by building a JReport Server EAR
●
Integrating by building a user WAR and embedding a self-contained JReport Server
●
Integrating by building a user EAR and embedding a self-contained JReport Server
Integrating by building a JReport Server WAR
The self-contained JReport Server can be deployed as a single WAR file. After specifying the
reporthome and configuring the database information, you can build the WAR file using the tool
makewar.bat/makewar.sh in <install_root>\bin. To generate the WAR file, execute the command
with the buildWar parameter. For example:
makewar.bat/makewar.sh buildWar
Structure of the JReport Server WAR
For example, here you can create a JReport Server WAR file named jreport.war. The structure of the
JReport Server WAR is as follows:
jreport.war
WEB-INF/
web.xml
lib/ -- This folder contains all resources in the JReport Server library.
admin/ -- This folder contains JSP files for the JReport Administration page.
jinfonet/ -- This folder contains JSP files for the JReport Console page.
dhtmljsp/ --This folder contains JSP files for viewing DHTML reports.
WEB-INF/web.xml
The following is the default content in the web.xml file of the JReport Server WAR:
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems,
Inc.//DTD Web Application 2.3//EN"
"http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app>
<listener>
<listener-class>jet.server.servlets.JRServerContextListener</listener-class>
</listener>
<servlet>
<servlet-name>jrserver</servlet-name>
<servlet-class>jet.server.servlets.JRServlet</servlet-class>
</servlet>
<servlet>
<servlet-name>sendfile</servlet-name>
<servlet-class>jet.server.servlets.SendFileServlet</servlet-class>
</servlet>
<servlet>
<servlet-name>dhtml</servlet-name>
<servlet-class>jet.web.dhtml.DHTMLlet</servlet-class>
</servlet>
<servlet>
<servlet-name>help</servlet-name>
<servlet-class>jet.web.dhtml.JHelplet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>jrserver</servlet-name>
<url-pattern>/jrserver/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>sendfile</servlet-name>
<url-pattern>/sendfile/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>dhtml</servlet-name>
<url-pattern>/dhtml/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>help</servlet-name>
<url-pattern>/help/*</url-pattern>
</servlet-mapping>
</web-app>
Integrating by building a JReport Server EAR
The self-contained JReport Server can be deployed as a single EAR file. After specifying the reporthome
and configuring the database information, you can build the EAR file using the tool makewar.bat/
makewar.sh in <install_root>\bin. To generate the EAR file, execute the command with the buildEar
parameter, for example:
makewar.bat/makewar.sh buildEar
Structure of the JReport Server EAR
For example, here you can create a JReport Server EAR file named jreport.ear. The structure of the
JReport Server EAR is as follows:
jreport.ear
META-INF/application.xml
jreport-lib/ -- This folder contains all resources in the JReport Server library.
jreport.war
META-INF/MANIFEST.MF
WEB-INF/web.xml
admin/
jinfonet/
dhtmljsp/
META-INF/application.xml
Following the Java EE standard, you should configure the META-INF/application.xml file before
deploying the EAR:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE application PUBLIC "-//Sun Microsystems, Inc.//DTD J2EE Application 1.3//EN"
"http://java.sun.com/dtd/application_1_3.dtd">
<application>
<display-name>Self-contained JReport Server</display-name>
<module id="JReportWebModule">
<web>
<web-uri>jreport.war</web-uri>
<context-root>jreport</context-root>
</web>
</module>
</application>
META-INF/MANIFEST.MF of Web module
Since the JReport Server library is included in jreport-lib of the EAR layer, you must specify Class-Path
in the META-INF/MANIFEST.MF file. The contents below should be included in the MANIFEST.MF file:
Class-Path: jreport-lib/jrenv.jar jreport-lib/JRESServlets.jar jreport-lib/JREngine.
jar ...
Class-Path is a list of all packages in the JReport Server library. Each package name should start with
the prefix jreport-lib/, and you should use a blank space to separate package names.
WEB-INF/web.xml of Web module
The contents in the web.xml of the JReport Server EAR are the same as the contents in web.xml of the
JReport Server WAR. See the section Integrating by building a JReport Server WAR for details.
Integrating by building a user WAR and embedding a self-contained JReport
Server
You can embed a self-contained JReport Server into your WAR.
Structure of the user WAR
For example, here you can create a WAR named MyApp.war, and then embed a self-contained JReport
Server inside it. The structure of your WAR may be as follows:
MyApp.war
WEB-INF/
web.xml
lib/ -- This folder contains all resources in the JReport Server library and your other jar
files.
classes/ -- This folder contains your servlet classes.
../../asset/images/
jsp/
If you put the JReport WAR related JSPs to a sub folder, for example, jreport, and this time the
structure of your WAR may be as follows:
MyApp.war
WEB-INF/
web.xml
lib/ -- This folder contains all resources in the JReport Server library and your other jar
files.
classes/ -- This folder contains your servlet classes.
../../asset/images/
jreport/
admin/
dhtmljsp/
jinfonet/
...
To run JReport reports, you must do the following configurations:
●
Add the following entry into web.xml:
<context-param>
<param-name>autoDetectServletPath</param-name>
<param-value>false</param-value>
</context-param>
WEB-INF/web.xml in the user WAR
You should add listener into the web.xml as follows:
<listener>
<listener-class>jet.server.servlets.JRServerContextListener</listener-class>
</listener>
Integrating by building a user EAR and embedding a self-contained JReport
Server
You can embed a self-contained JReport Server into your EAR in order to use JReport Server from EJB.
Structure of the user EAR
For example, here you can create an EAR named MyApp.ear and then embed a self-contained JReport
Server inside it. In the EAR, there is an EJB module used for initializing JReport Server. The structure of
your EAR may be as follows:
MyEAR.ear
META-INF/application.xml
jreport-lib/ -- This folder contains all resources in the JReport Server library
MyEjb.jar
META-INF/
MANIFEST.MF
ejb-jar.xml
com/
META-INF/application.xml
Following the Java EE standard, you should configure the META-INF/application.xml file before
deploying your EAR:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE application PUBLIC "-//Sun Microsystems, Inc.//DTD J2EE Application 1.3//EN"
"http://java.sun.com/dtd/application_1_3.dtd">
<application>
<display-name>EJB with Embedded JReport Server</display-name>
<module id="MyEJBModule">
<ejb>MyEjb.jar</ejb>
</module>
</application>
META-INF/MANIFEST.MF of EJB module
Since the JReport Server library is included in the jreport-lib folder of the EAR layer, you must specify
Class-Path in the META-INF/MANIFEST.MF file. The contents below should be included in the MANIFEST.
MF file:
Class-Path: jreport-lib/jrenv.jar jreport-lib/JRESServlets.jar jreport-lib/JREngine.
jar ...
Class-Path is a list of all packages in the JReport Server library. Each package name should start with
the prefix jreport-lib/, and you should use a blank space to separate package names.
META-INF/ejb-jar.xml
If you do not want to set the reporthome for the embedded self-contained JReport Server, but instead
want to use JReport's default settings, there is no requirement for configuring the ejb-jar.xml.
However, if you want to control the reporthome of the JReport Server, or specify a JNDI data source for
JReport Server to use, you should first configure the ejb-jar.xml file using the <env-entry></enventry> tags.
Here is an example:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE ejb-jar PUBLIC "-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 2.0//EN"
"http://java.sun.com/dtd/ejb-jar_2_0.dtd">
<ejb-jar id="ejb-jar_ID">
<display-name>MyEJB</display-name>
<enterprise-beans>
<session id="JReportEJB">
<ejb-name>JRptServer</ejb-name>
<home>demo.JRptServerHome</home>
<remote>demo.JRptServer</remote>
<ejb-class>demo.JRptServerBean</ejb-class>
<session-type>Stateless</session-type>
<!-- Specify JReport reporthome directly
<env-entry>
<env-entry-name>jreport.rpthome</env-entry-name>
<env-entry-value>/home/jreport</env-entry-value>
<env-entry-type>java.lang.String</env-entry-type>
</env-entry>
-->
<!-- JReport callback my CustomizedServerEnv -->
<env-entry>
<env-entry-name>jreport.servenv</env-entry-name>
<env-entry-value>demo.JReportServerEnv</env-entry-value>
<env-entry-type>java.lang.String</env-entry-type>
</env-entry>
<transaction-type>Bean</transaction-type>
</session>
</enterprise-beans>
</ejb-jar>
Deploying JReport Server to a Java application server
After you have created a WAR/EAR file that includes a self-contained JReport Server, you can deploy
the WAR/EAR to an application server following the deploying instructions of the application server.
This section provides examples of deploying JReport Server to several leading Java EE application
servers. The instructions are applicable to Unix, z/Linux and Windows platforms. However, the paths
for Windows should use the Windows format, for example, C:\JReport\Server, while paths for Unix
and z/Linux should use the Unix and z/Linux format, for example, /opt/JReport/Server.
Before going on to the next sections, you should already have reviewed Building a WAR/EAR file to
include a self-contained JReport Server.
The following examples are based on the Unix platform with one exception of Sun Application Server on
Windows:
●
Deploying to IBM WebSphere 7
●
Deploying to WebLogic 11g Release 1 (10.3.2)
●
Deploying to Tomcat 7.0.27
●
Deploying to JBoss 5.0.1
●
Deploying to OC4J 10g R3 (10.1.3.5.0)
●
Deploying to Sun Java™ System Application Server Platform Edition 9.1
●
Deploying to Jetty 9.1
●
Deploying to GlassFish V3
Notes:
●
It is supported if you change the location of the two folders, skin and dhtmljsp, which are in the
\public_html directory in the application server side. What is need is creating a file jrserver.
properties in the \WEB-INF directory and then adding the following two properties and providing the
correct paths (the context root is excluded):
web.skin.dir
web.dhtml_jsp_path
●
JReport Server cannot be integrated with JBoss 7.
Deploying to IBM WebSphere 7
The example directory paths listed below are based on Solaris or Linux (referred to as Unix). The
instructions are applicable to both Unix and Windows installations; however, the format of the paths for
Windows would use the Windows format, i.e. C:\JReport\Server instead of /opt/JReport/Server.
It is assumed that:
●
●
WebSphere 7 is installed in the /opt/IBM/WebSphere7/AppServer directory.
The JReport Server WAR file jreport.war is located in the /opt/JReport/Server/bin/distribute
directory. To create the WAR file, refer to the instructions in Building a WAR/EAR file to include a selfcontained JReport Server.
To deploy JReport Server to IBM WebSphere:
1. Copy Derby jars in /opt/JReport/Server/derby to the /opt/IBM/WebSphere7/AppServer/lib
directory.
2. Start IBM WebSphere. Use the shell script /opt/IBM/WebSphere7/AppServer/bin/startServer.
sh <servername> to start the server. The default server name is server1.
3. Access the WebSphere Administrative Console by using the URL: http://hostname:9060/ibm/
console, where the hostname is host name or IP address, and 9060 is the port number.
4. The login requires user name and password.
5. After successfully log in, expand the Applications node, select Application Types and then
Websphere enterprise applications.
6. Click Install.
7. Click Browse to select the jreport.war file, and then click Next.
8. Keep clicking Next until you see the requirement for specifying context root.
9. In the Context Root field, type a context path such as /jreport/, then click Next.
10. Click Finish on the Summary page. The installing process may take several minutes, wait until the
process is completed.
11. Click Save.
12. Select jreport.war and then click Start to start JReport Server.
13. Access JReport Server using the following URL:
http://<hostname>:9080/jreport/jrserver
http://<hostname>:9080/jreport/admin/index.jsp
http://<hostname>:9080/jreport/jinfonet/index.jsp
Troubleshooting
If you run into problems when using JReport Server in IBM WebSphere, send the log files of JReport
Server to [email protected] The following procedure illustrates how to generate the log files:
1. Type -Dlogall=true in the Generic JVM arguments field. Go to Application servers > server1 >
Process Definition > Java Virtual Machine to access this field.
2. Restart the application server, and try to reproduce the problem. After reproducing the problem,
send [email protected] the log files in reporthome/logs.
The WebSphere log files may also help to identify the problem. The most useful one is in /opt/
IBM/WebSphere7/AppServer/profiles/AppSrv01/logs/server1/SystemErr.log.
Note: For WebSphere Application Server Liberty Profile V8.5.5.2, you need to do the following:
●
Configure JNDI so as for the reporthome to be generated successfully. Add the following lines in
server.xml located in ${WebSphere_home}/usr/servers/defaultServer:
<featureManager>
<feature>jndi-1.0</feature>
</featureManager>
●
Extract jreport.war to ${wlphome}/usr/servers/defaultServer/dropins and then start
WebSphere Application Server Liberty Profile V8.5.5.2. In this way the sample reports will be able to
run well.
Deploying to WebLogic 11g Release 1 (10.3.2)
The example directory paths listed below are based on Solaris or Linux (referred to as Unix). The
instructions are applicable to both Unix and Windows installations; however, the format of the paths for
Windows would use the Windows format, i.e. C:\JReport\Server instead of /opt/JReport/Server.
It is assumed that:
●
●
WebLogic 11g Release 1 (10.3.2) is installed in the /opt/bea directory. This is referred to as
BEA_HOME in the WebLogic documentation.
The JReport Server WAR file jreport.war is located in the /opt/JReport/Server/bin/distribute
directory. To create the WAR file refer to the instructions in Building a WAR/EAR file to include a selfcontained JReport Server.
To deploy JReport Server to BEA WebLogic:
1. If you have not already created a WebLogic Domain for JReport Server you must create one
before starting the integration.
2. Start WebLogic by running startWeblogic.sh in /opt/bea/user_projects/domains/domain_name/
bin.
3. Access the WebLogic Administrative Console by using URL http://hostname:7001/console/,
where the hostname is host name or IP address, and 7001 is the port number.
4. After your successful login, in the Domain Structure panel on the left, click Deployments node.
5. In the Summary of Deployments panel, click Install.
6. In the Install Application Assistant panel, click the upload your file(s) link.
7. In the Deployment Archive section, click Browse to select the jreport.war file in C:\JReport
\Server\bin\distribute, and then click Next.
8. Keep clicking Next until the Finish button is enabled, and then click Finish.
9. Start JReport Server and then access it using the following URL:
http://localhost:7001/jreport/
Troubleshooting
If you run into problems when using JReport Server in BEA WebLogic, send the log files of JReport
Server to [email protected] The following procedure illustrates how to generate the log files:
1. Add -Dlogall=true on the same line as -Dreporthome in the startWebLogic.sh shell script.
2. Restart the application server, and then try to reproduce the problem. After reproducing the
problem, send [email protected] the log files in reporthome/logs.
The WebLogic log file may also help to identify the problem. It is /opt/bea/user_projects/
domains/domain_name/logs.
Deploying to Tomcat 7.0.27
The example directory paths listed below are based on Solaris or Linux (referred to as Unix). The
instructions are applicable to both Unix and Windows installations; however, the format of the paths for
Windows would use the Windows format, i.e. C:\JReport\Server instead of /opt/JReport/Server.
It is assumed that:
●
●
Tomcat 7.0.27 is installed in the /opt/apache-tomcat-7.0.27 directory.
The JReport Server WAR file jreport.war is located in the /opt/JReport/Server/bin/distribute
directory. To create the WAR file refer to the instructions in Building a WAR/EAR file to include a selfcontained JReport Server.
To deploy JReport Server to Tomcat 7.0.27:
1. Ensure that Tomcat is shut down.
2. Copy the Web Application Archive jreport.war to /opt/apache-tomcat-7.0.27/webapps.
3. Start Tomcat by running the startup.sh script.
4. Access JReport Server using the following URLs:
http://hostname:8080/jreport/jrserver
http://hostname:8080/jreport/admin/index.jsp
http://hostname:8080/jreport/jinfonet/index.jsp
Troubleshooting
If you run into problems when using JReport Server in Tomcat, send the log files of JReport Server to
[email protected] The following procedure illustrates how to generate the log files:
1. Modify the catalina.sh file in /opt/apache-tomcat-7.0.27/bin.
In the file catalina.sh, add -Dlogall=true after the reporthome definition:
JAVA_OPTS="-Dreporthome=/opt/JReport/Server -Dlogall=true"
Cygwin=false
Or if no reporthome is specified, add as follows:
JAVA_OPTS=-Dlogall=true
Cygwin=false
2. After editing catalina.sh, start Tomcat.
3. To get the information about the JReport Server environment, you can access http://
hostname:8080/jreport/admin/info.jsp?cmd=info.
4. Save the output to a file.
5. After reproducing the problem, send [email protected] the log files in reporthome/logs.
The Tomcat log files may also help to identify the problem. The most useful one is /opt/apachetomcat-7.0.27/logs/catalina.out.
Deploying to JBoss 5.0.1
The example directory paths listed below are based on Solaris or Linux (referred to as Unix). The
instructions are applicable to both Unix and Windows installations; however, the format of the paths for
Windows would use the Windows format, i.e. C:\JReport\Server instead of /opt/JReport/Server.
It is assumed that:
●
●
JBoss 5.0.1 is installed in the /opt/jboss directory.
The JReport Server WAR file jreport.war is located in the /opt/JReport/Server/bin/distribute
directory. To create the WAR file refer to the instructions in Building a WAR/EAR file to include a selfcontained JReport Server.
To deploy JReport Server to JBoss 5.0.1:
1. Ensure that JBoss is shut down by running the script /opt/jboss/bin/shutdown.sh -S.
2. Remove the two files xercesImpl.jar and xml-apis.jar from jreport.war since they conflict with
JBoss. They are located in jreport.war\WEB-INF\lib.
3. Unzip jreport.war and name the unzipped folder as jreport.war, then copy the folder to /opt/
jboss/server/default/deploy.
4. Start JBoss by running the run.sh script.
5. Access JReport Server using the following URLs:
http://localhost:8080/jreport/jrserver
http://localhost:8080/jreport/admin/index.jsp
http://localhost:8080/jreport/jinfonet/index.jsp
Troubleshooting
If you run into problems when using JReport Server in JBoss, send the log files of JReport Server to
[email protected] The following procedure illustrates how to generate the log files:
1. Modify the file run.sh in /opt/jboss/bin.
In the file run.sh, add -Dlogall=true after the reporthome definition:
"$JAVA" $JAVA_OPTS \
-classpath "$JBOSS_CLASSPATH" -Dreporthome=/opt/JReport/Server \
-Dlogall=true \
org.jboss.Main "[email protected]"
2. After editing run.sh, start JBoss using the modified file.
3. After reproducing the problem, send [email protected] the log files in reporthome/logs.
The JBoss log files may also help to identify the problem. The most useful one is /opt/jboss/
server/default/log/server.log.
Notes:
For JBoss AS 7/EAP 6:
●
❍
❍
●
To resolve the issue that JBoss AS 7/EAP 6 cannot locate jrenv.jar, when building a WAR/EAR
to deploy to JBoss AS 7/EAP 6, add -Djbossas7=true in makewar.bat/sh.
Formulas cannot be compiled when running sample reports. To resolve this, you need to use
JReport Designer to compile formulas by publishing the reports to the integrated JReport Server
once again.
Deploying jreport.war to JBoss AS 7 costs some time, when there is a setting deploymenttimeout="60" in <JBoss_home>/standalone/configuration/standalone.xml, change the value to
180 (seconds) or a bigger number.
For JBoss EAP 6.1/6.2:
●
❍
After jreport.war is generated, you need to create a file named iboss-deployment-structure.xml in
the jreport.war/META-INF directory. The file should contain the following contents:
<?xml version="1.0" encoding="UTF-8"?>
<jboss-deployment-structure>
<deployment>
<exclusions>
<module name="org.apache.log4j" />
</exclusions>
</deployment>
</jboss-deployment-structure>
❍
JReport cannot be deployed to JBoss EAP 6.1/6.2 which uses JDK1.8.
Deploying to OC4J 10g R3 (10.1.3.5.0)
It is assumed that the JReport Server WAR file jreport.war is located in the /opt/JReport/Server/bin/
distribute directory. To create the WAR file refer to the instructions in Building a WAR/EAR file to
include a self-contained JReport Server.
To deploy JReport Server to OC4J 10g R3 (10.1.3.5.0):
1. Start OC4J.
2. On the Applications tab, click Deploy.
3. In the Archive Location section, click Browse to select the jreport.war file in /opt/JReport/
Server/bin/distribute. Then click Next.
4. Type JRServer in the Application Name field, and type a context path such as /jreport in the
Context Root field. Then click Next.
5. Click Deploy to deploy the WAR.
6. Access JReport Server using the following URLs:
http://localhost:port/jreport/jrserver
http://localhost:port/jreport/admin/index.jsp
http://localhost:port/jreport/jinfonet/index.jsp
Troubleshooting
If you run into problems when using JReport Server in the Oracle oc4j Application Server, send the log
files of JReport Server to [email protected] The following procedure illustrates how to generate
the log files:
1. Type -Dlogall=true in oc4j located in /oc4jhome/bin.
2. Restart OC4J, and then try to reproduce the problem.
3. After reproducing the problem, send [email protected] the log files in reporthome/logs.
Deploying to Sun Java™ System Application Server Platform
Edition 9.1
The example directory paths listed below are based on Windows. The instructions are applicable to both
Unix and Windows installations; however, the format of the paths for Unix would use the Unix format, i.
e. /opt/JReport/Server instead of C:\JReport\Server.
It is assumed that:
●
●
Sun Java™ System Application Server Platform Edition 9.1 is installed in the C:\Sun\AppServer
directory.
It is assumed that the JReport Server WAR file jreport.war is located in the C:\JReport\Server\bin
\distribute directory. To create the WAR file refer to the instructions in Building a WAR/EAR file to
include a self-contained JReport Server.
To deploy JReport Server to Sun Java™ System Application Server Platform Edition 9.1:
1. Update Sun Application Server's Derby jars by using the lib folder in C:\JReport\Server\derby to
replace the lib folder in C:\Sun\AppServer\javadb\lib.
2. Start the Sun Application Server by selecting Start > Programs > Sun Microsystems >
Application Server PE > Start Default Server.
3. Launch the Admin Console by selecting Start > Programs > Sun Microsystems > Application
Server PE > Admin Console.
4. In the left console tree, expand the Applications node, then click Web Applications.
5. In the Web Applications page, click Deploy.
6. Select the radio button before Local packaged file or directory that is accessible from the
Application Server, then click Browse Files to select the WAR file jreport.war.
7. Use the default settings and click OK. You will find a new application jreport is listed.
8. Access JReport Server using the following URLs:
http://<hostname>:8080/jreport/jrserver
http://<hostname>:8080/jreport/jinfonet/index.jsp
http://<hostname>:8080/jreport/admin/index.jsp
Troubleshooting
If you run into some problems when using the Sun Application Server, send the log files of JReport
Server to [email protected] The following procedure illustrates how to generate the log files:
1. Start the Sun Application Server, and then launch the Admin Console.
2. In the console tree, click Application Server.
3. Go to the JVM Settings tab, and then click JVM Options.
4. In the JVM Option field, click Add JVM Option, and then type -Dlogall=true.
5. Click Save to save your changes.
6. Restart Sun Application Server and try to reproduce the problem.
7. After reproducing the problem, send [email protected] the log files in reporthome/logs.
Deploying to Jetty 9.1
The example directory paths listed below are based on Solaris or Linux (referred to as Unix). The
instructions are applicable to both Unix and Windows installations; however, the format of the paths for
Windows would use the Windows format, i.e. C:\JReport\Server instead of /opt/JReport/Server.
It is assumed that the JReport Server WAR file jreport.war is located in the /opt/JReport/Server/bin/
distribute directory. To create the WAR file refer to the instructions in Building a WAR/EAR file to
include a self-contained JReport Server.
To deploy JReport Server to Jetty 9.1:
1. If you are integrating JReport Server with Jetty in a non-remote environment, you need to remove
or comment the following codes in the web.xml of jreport.war:
<login-config>
<auth-method>BASIC</auth-method>
</login-config>
2. Add jreport.war to the /opt/Jetty9.1/webapps directory.
3. Start Jetty 9.1.
4. Access JReport Server using the following URLs:
http://<hostname>:8080/jreport/jrserver
http://<hostname>:8080/jreport/admin/index.jsp
http://<hostname>:8080/jreport/jinfonet/index.jsp
Deploying to GlassFish V3
The example directory paths listed below are based on Solaris or Linux (referred to as Unix). The
instructions are applicable to both Unix and Windows installations; however, the format of the paths for
Windows would use the Windows format, i.e. C:\JReport\Server instead of /opt/JReport/Server.
It is assumed that the JReport Server WAR file jreport.war is located in the /opt/JReport/Server/bin/
distribute directory. To create the WAR file refer to the instructions in Building a WAR/EAR file to
include a self-contained JReport Server.
To deploy JReport Server to GlassFish V3:
1. Start the GlassFish in the default domain1 and then launch the Admin Console.
2. Click the Applications node on the left.
3. Click Deploy on the displayed page.
4. Click Choose File to select the WAR file jreport.war.
5. Leave Application Name and Context Root as jreport and jreport. Then click OK.
6. Expand the Deployment node on the left and you will see a new node named jreport. Click jreport
and then on the displayed page click Save.
7. In the console tree, click Configuration. Go to the JVM Settings tab, and then click JVM Options.
In the JVM Options section, click Add JVM Option, and then type -Djava.awt.headless=true.
Click Save to save your changes.
You need not add this JVM option if you are using Windows.
8. Restart GlassFish, and then start the application jreport.
9. Access JReport Server using the following URLs:
http://<hostname>:8080/jreport
http://<hostname>:8080/jreport/admin/index.jsp
http://<hostname>:8080/jreport/jinfonet/index.jsp
Note: GlassFish 3.1.2 uses a different Derby driver from JReport which leads to that the JReport War
file does not work in GlassFish 3.1.2. To solve this, you can replace the files in /opt/glassfish3.1.2/
javadb/lib with the jar files in /opt/JReport/Server/derby/lib, or use the folder /opt/
glassfish3.0.2/javadb/lib to replace the folder /opt/glassfish3.1.2/javadb/lib if GlassFish
3.0.2 resources are available.
Troubleshooting
If you run into some problems when using the GlassFish V3, send the log files of JReport Server to
[email protected] The following procedure illustrates how to generate the log files:
1. Start the GlassFish in the default domain1 and then launch the Admin Console.
2. In the console tree, click Configuration.
3. Go to the JVM Settings tab, and then click JVM Options.
4. In the JVM Options section, click Add JVM Option, and then type -Dlogall=true. Click Save to
save your changes.
5. Restart GlassFish and try to reproduce the problem.
6. After reproducing the problem, send [email protected] the log files in reporthome/logs.
The GlassFish log file may also help to identify the problem. It is /opt/glassfish/domains/domain1/
logs/server.log.
Integrating remote JReport Server
Normally, JReport servlets are only integrated with other applications on the same machine. However,
you can now implement JReport Remote Server API in your JSPs, and integrate the JSPs with the
application server to call JReport Server, which is running on a different machine.
Notes:
●
In a remote integration environment, the options for publishing resources are hidden since they are
not supported by JReport JSPs. If you want to publish reports or catalogs to JReport Server, use one
of the following ways:
❍
❍
❍
●
●
●
Access the JReport Server (not the remote server) Administration page with 8889 as the default
port to perform publish work.
Copy the report or catalog files to the computer where JReport Server (not the remote server) is
located, and then call the RMI API to publish them.
Publish the report or catalog files from JReport Designer to the JReport Server.
In a remote integration environment, running reports to the Applet format is not supported.
In a remote integration environment, the two tabs Monitor and Data are hidden on JReport
Administration page since they are not supported.
You can change the location of the two folders, skin and dhtmljsp, in the \public_html directory in
the application server side. What is required is to create a file jrserver.properties in the \WEB-INF
directory and then add the following two properties and provide the correct paths (the context root is
excluded):
web.skin.dir
web.dhtml_jsp_path
See the following cases:
●
Integrating remote JReport Server with IBM WebSphere 7 by a WAR file
●
Integrating remote JReport Server with WebLogic 11g Release 1 (10.3.2) by a WAR file
Related Topics:
●
Overall Remote Server APIs & unified JSPs
Integrating remote JReport Server with IBM WebSphere 7 by a
WAR file
Here is an example illustrating the case of using JSPs based on Remote Server APIs to integrate with
IBM WebSphere 7.
It is assumed that:
●
WebSphere 7 is installed in C:\WebSphere in computer A.
●
JReport Server is installed in C:\JReport\Server in computer B. The computer IP is 127.0.0.1.
Take the following steps to integrate remote JReport Server with IBM WebSphere:
1. Generate a WAR file.
2. Configure JReport Server.
3. Deploy the WAR file.
Below show the details for each step:
Generating the WAR file
1. In computer B, use the tool makewar.bat to build the JReport Server WAR file as defined by
makewar.xml for remote integration. Both makewar.bat and makewar.xml are located in C:
\JReport\Server\bin. Run the following commands in DOS window and the generated WAR file
remote.war will be saved to the directory C:\JReport\Server\bin\distribute.
makewar.bat buildRemoteWar -Djrs.remote.host=127.0.0.1 -Djrs.remote.rmiport=1129 Djrs.rmi.auth_file=C:\JReport\Server\bin\rmi.auth
2. Copy the rmi.auth file from C:\JReport\Server\bin in computer B to C:\JReport\Server\bin in
computer A.
Configuring JReport Server
1. Make sure JReport Server has been started once in order that the server.properties file is
generated.
2. Change server.properties file in C:\JReport\Server\bin as follows:
server.rmiserver.enable=true
server.rmiadminservice.enable=true
Deploying the WAR file
1. In computer A, start IBM WebSphere.
2. In computer B, access the WebSphere Administrative Console by using the URL: http://
hostname:9060/ibm/console, where the hostname is computer A's host name or IP address, and
9060 is the port number.
3. After successfully log in, expand the Applications node, select Application Types and then
Websphere enterprise applications.
4. Click Install.
5. Click Browse to select the remote.war file, and then click Next.
6. Keep clicking Next until you see the requirement for specifying context root.
7. In the Context Root field, type a context path such as /remote/, then click Next.
8. Click Finish on the Summary page. The installing process may take several minutes, wait until the
process is completed.
9. Click Save.
10. Select remote.war and then click Start.
11. Access JReport Server using the following URL:
http://hostname:9080/remote/jinfonet/default.jsp
Here the hostname is computer A's host name or IP address.
Integrating remote JReport Server with WebLogic 11g Release 1
(10.3.2) by a WAR file
Here is an example illustrating the case of using JSPs based on Remote Server APIs to integrate with
WebLogic 11g Release 1 (10.3.2).
It is assumed that:
●
WebLogic is installed in C:\bea in computer A.
●
JReport Server is installed in C:\JReport\Server in computer B. The computer IP is 127.0.0.1.
Take the following steps to integrate remote JReport Server with WebLogic:
1. Generate a WAR file.
2. Configure JReport Server.
3. Deploy the WAR file.
Below show the details of each step:
Generating a WAR file
1. In computer B, use the tool makewar.bat to build the JReport Server WAR file as defined by
makewar.xml for remote integration. Both makewar.bat and makewar.xml are located in C:
\JReport\Server\bin. Run the following commands in DOS window and the generated WAR file
remote.war will be saved to the directory C:\JReport\Server\bin\distribute.
makewar.bat buildRemoteWar -Djrs.remote.host=127.0.0.1 -Djrs.remote.rmiport=1129 Djrs.rmi.auth_file=C:\JReport\Server\bin\rmi.auth
2. Copy the rmi.auth file from C:\JReport\Server\bin in computer B to C:\JReport\Server\bin in
computer A.
Configuring JReport Server
1. Make sure JReport Server has been started once in order that the server.properties file is
generated.
2. Change server.properties file in C:\JReport\Server\bin as follows:
server.rmiserver.enable=true
server.rmiadminservice.enable=true
Deploying the WAR file
1. If you have not already created a WebLogic Domain for JReport Server you must create one
before starting the integration.
2. In computer A, start WebLogic by running startWeblogic.sh in C:\bea\user_projects\domains
\domain_name\bin.
3. In computer B, access the WebLogic Administrative Console by using URL http://hostname:7001/
console/, where the hostname is computer A's host name or IP address, and 7001 is the port
number.
4. After your successful login, in the Domain Structure panel on the left, click Deployments node.
5. In the Summary of Deployments panel, click Install.
6. In the Install Application Assistant panel, click the upload your file(s) link.
7. In the Deployment Archive section, click Browse to select the remote.war file in C:\JReport
\Server\bin\distribute, and then click Next.
8. Keep clicking Next until the Finish button is enabled, and then click Finish.
9. Start JReport Server in computer B. Then go to computer A and access JReport Server using the
following URL:
http://localhost:7001/remote/
JReport Server Cluster
A JReport Server Cluster is a distributed cluster in which a group of servers work together to provide
cluster-wide shared resources, security, schedules, and version services. In a JReport Server Cluster,
all clustered servers play exactly the same role. You can add a new server to the existing cluster or
shut down a server from the cluster any time.
This chapter shows you the infrastructure of the JReport Server Cluster, what features it owns, how to
set it up, and how to manage it.
The following topics are covered:
●
Cluster overview
●
JReport Server Cluster main features
●
Setting up and starting a JReport Server Cluster
●
Managing a JReport Server Cluster
●
Dispatching RMI Server Pages requests in multiple server environment
Note: A JReport Server Cluster license is required in order to use this feature. If you do not have a
cluster license please contact your Jinfonet Software account manager to obtain a license.
Cluster overview
There are many nodes (clustered servers) that play the same role in a JReport Server Cluster. The following is a
diagram of the JReport Server Cluster infrastructure:
Every clustered server in this distributed cluster has the same responsibility. You can set each clustered server in a
JReport Server Cluster by configuring its properties. The following list shows all the tasks each clustered server in the
server cluster can complete.
Business tasks
Run
Reports
Clustered
Server
Submit
Scheduled
Tasks
Y
Related topics:
●
JReport Server Cluster
Y
Administrative tasks
LoadBalancing
Y
Failover
Y
LoadBalancing
Administration
Security
Administration
Resource
Administration
Y
Y
Y
JReport Server Cluster main features
This section describes the main features of the JReport Server Cluster. Some of these features are also
available through the API. With these features in mind, you will be better able to understand JReport
Server Clusters and easily use them.
Administering security and resources
In a distributed cluster, you can accomplish all administrative tasks from any single node.
After logging onto the cluster from a clustered server as an administrator, certain security
administrative tasks can be performed:
●
Create, remove and edit users, groups, realms, protections and ACLs.
●
Edit resource nodes and sub resource nodes. Add reachable virtual resource nodes.
●
Customize the default page appearance for users.
Load balancing
Here are the benefits of deploying load balancing in a JReport Server Cluster.
●
Automatically allocates tasks to suitable servers according to their current load and performance.
●
Makes sure that all of the servers in the cluster are fully utilized.
●
Automatically re-balances the network load when one server is added or removed.
For scheduled tasks and tasks submitted from interactive reports (reports that run on Page Report
Studio, Web Report Studio, JDashboard or Visual Analysis), JReport adopts different load balancing
mechanisms to enable the servers to work more effectively.
Load balancing for interactive reports
When running interactive reports in a cluster environment, JReport's built-in dispatcher or a usercustomized dispatcher would be used to do load balancing.
JReport's built-in dispatcher is implemented on report level. It uses an internal load balancing algorithm
which relies on computing resources such as memory and CPU usage to balance load. When an
interactive report is opened, JReport will compute those resources and then allocate the most suitable
server to the report. All later requests from the report will be performed on the server thereafter.
Customized dispatchers, which are difficult to implement, would be used quite rarely and only for
special cases. That's because, when using customized dispatcher to do load balancing for interactive
reports, firstly you need to provide all server nodes in the cluster in advance, and what's more, only
session level dispatcher could be implemented.
Load balancing for scheduled tasks
Cluster Scheduler Lease
Every clustered server has a scheduler, and among the schedulers those with a lease are active
schedulers. When the time of a scheduled task arrives, active schedulers compete and the winner gets
to trigger the schedule. When dispatching tasks, the server which has the active scheduler will select a
server according to load balancing algorithm and allocate the task to it.
By default, in a JReport Server Cluster all nodes of the cluster compete to become the active scheduler
when the time of a scheduled task arrives. If the scheduled task has been bound with a trigger, then
the node who gets the trigger becomes the active scheduler. The active scheduler for the task will then
determine the server that will be asked to run the scheduled report based on load balancing. The
Cluster Scheduler Lease option allows you to limit the number of servers competing for each scheduled
report by setting a Cluster Scheduler Lease Active Count. As long as the count is less than the total
number of nodes in the cluster, only the nodes holding a lease will compete to become the scheduler
for the report that is ready to run. Depending on the number of scheduled reports you have, you may
find that setting the Lease Active Count to 1 or 2 will provide more overall throughput on the system so
the other nodes never have to be concerned about scheduled tasks.
There are two additional parameters that can be set:
●
●
Cluster Scheduler Lease Valid Time will set the amount of time that the lease holder will continue to
compete for scheduled tasks to run. The default value is 300 seconds.
Cluster Schedule Lease Check Interval will set the amount of time between when other non-lease
nodes will check to see if a lease is available to pick up. The default value is 30 seconds, i.e. every 30
seconds all the other nodes will check to see if one of the lease semaphores is available to take. The
number of semaphores is set by the Cluster Scheduler Lease Active Count.
Load detection
There is a JReport Server residing in each node of a JReport Server Cluster. The main factor that
affects load balancing is the number of concurrent reports that are running on every JReport Server. In
order to avoid heavy load, every member server in the cluster has been enabled to send the number of
concurrently running reports on it to the other cluster nodes.
Built-in load balancing algorithms
JReport Server Cluster supports several algorithms for load balancing clustered servers. Configurable
algorithms for load balancing clustered servers are:
●
●
●
Min-load (loadbalance.type=0)
The server that has the active scheduler will select the server which has the least number of
currently running reports. If the local server is one of the qualified servers, it will be given higher
priority.
Round Robin (loadbalance.type=1)
The server that has the active scheduler will select each server in sequence one by one until each has
been allocated a report to run then will repeat the cycle. This is the default setting.
Weighted Min-load (loadbalance.type=2)
The server that has the active scheduler will select the server that has the least weighted current
reports. If the local server is one of the qualified servers, it will be given higher priority.
Number of currently running reports
Weighted current reports=
Performance Weight
Performance weight is a positive floating point number that you set to each server in a cluster on any
clustered server. Use JReport Administration page > Cluster > Weight panel and measure the
performance of a typical report on each node of the cluster. The higher performance weight you set
to a clustered server, the higher chance it may get selected by the server that holds the active
scheduler during load balancing. See Configuring performance weight for how to set performance
weight and how this algorithm works.
If you do not set performance weight, by default the algorithm will work the same as Round Robin.
●
Random (loadbalance.type=3)
The server that holds the active scheduler will select the server randomly.
Failover
You can check the status of the clustered servers on JReport Server Monitor and notice the failure of
any member server. If a member server is down, JReport cluster will remove it from the active
clustered server list.
Member server failure
●
●
●
Effect on load balancing
When JReport cluster detects a failed member server, it will remove the member server from the
active server list and will not schedule reporting tasks to that server any more. Load balancing will
proceed on the remaining active servers.
Effect on incomplete tasks
When JReport cluster detects a failed clustered server, it will check the shared table for the list of
incomplete tasks and will then reassign all incomplete tasks to other active servers using the load
balancer.
Effect on completed tasks
JReport supports only report level recovery but not session level recovery. Once a report task is
completed, it will be written to temporary storage for redirection to the requester. Failure after that
will not be recovered.
Notifying of server down
If you have enabled the notifying of server down feature, when a member server crashes or is
disconnected with the cluster, JReport cluster will send a notification e-mail to a specified address.
Distributed storage
In a pure distributed cluster the resource files are not stored in a central place. Each server has its own
directories to be able to hold all types of resources including catalogs, templates, dashboards and
report results. The sharing of resources among servers is achieved via a copying mechanism. More
copies of resources reduce the possibility of resources being lost if a server goes down. However,
making too many copies consumes system resources by making copies that are never used.
There are two copying scenarios. One is when a resource is saved, JReport will copy the resource to
other randomly selected servers within the cluster, according to an argument: the number of copies
allowed for this type of resource. The saved resource itself is regarded as a copy. That is, in the case
when copy number is three, two other random servers will each be given a copy of the resource.
The other is on demand when a resource does not exist on the local server. JReport will search among
the other servers for the resource and copy it to the local server.
The controllable number of copies argument is available to administrator users on the JReport
Administration page > Cluster > Configuration panel. These types of resources support distribution:
history resources which are resources saving into the versioning system, realm resources, CRD results
that are cached report results, and memory storage related resources. You will be able to find the
number of copies setting for each type.
The best number to use for each resource depends on two factors, how many points of failure do you
want to tolerate and how often resources which are not local are requested by users. For example on a
10 node system, you might want to still run in case any two nodes go down. In this case, you would
want the number of copies to be three. Any two nodes could go down and there would still be one with
a copy of the resources. However, if there is a lot of on-demand requests that require copies you
might find that a higher number actually provides better average performance for your users since they
are not waiting for resources when they make on-demand requests.
Setting up and starting a JReport Server Cluster
This section introduces the steps for setting up a JReport Server Cluster and starting it. Here, it is
assumed that you already have a general idea about the infrastructure of JReport Server Clusters and
know the functions of the clustered servers. If this isn't the case, see Cluster overview and JReport
Server Cluster.
Following are steps and examples for how to set up and start a JReport Server Cluster:
●
Preparation
●
Setting up and configuring a JReport Server Cluster
●
Starting a JReport Server Cluster
●
Example 1: Setting up a simple JReport Server Cluster
●
Example 2: Setting up a JReport Server Cluster for a production environment
Preparation
To set up a JReport Server Cluster, you must determine the following factors:
●
What is a JReport cluster?
JReport cluster is based on JGroups and is a distributed cluster. All clustered servers in JReport
cluster play the same role. You can add a new server to the existing cluster or shut down a server
from the cluster any time.
●
How many servers will be included in the cluster?
The maximum number of servers is unlimited as long as you install JReport Server with the license
key for cluster. Based on your expected load and protection from system failures you can create 2 or
more nodes for your cluster. Often with multi-cpu and multi-core systems you will get better overall
throughput having several nodes on a single server. Only by testing in your environment will you be
able to find the number of nodes to give you the highest performance. Too few and resources will be
under utilized and too many will cause thrashing and lower throughput.
●
Whether to use the distributed storage feature in the cluster?
In a distributed cluster the files may be stored on any node in the cluster. You can set how many
copies will be made in the cluster and if you need to access the files from another node, JReport
cluster will copy them to this node from the node it is stored on. As a result, you can access your
required files from anywhere in the cluster. If the copy number is 0, then it means every node of the
cluster will get a copy.
The tradeoff is overall system performance versus individual user performance when a user requests
a report result. If you set Number of Copies to 0, the system will copy every resource file to every
node, slowing overall throughput considerably. However, setting Number of Copies to 1 will keep a
single copy just on the node where it was created which provides maximum system throughput but
when a user requests a resource which is not on his node he then needs to wait for it to be copied
before he can view it. If the node goes down though then the resource is unreachable. A setting of 2
is the default which allows for failover if a node goes down but just does a single copy.
●
Whether to use the default Derby DBMS or use your own DBMS?
JReport includes the Apache Derby DBMS for the server data such as resources and users, groups
and roles and a lot of other information. By default each installed node creates it's own database in
<install_root>/derby. In order to use a JReport cluster, all nodes must use the same database.
Select one of the nodes to manage the Derby DBMS and ensure that all the other nodes point to this
same instance. For an example, review the sample configuration Case 1.
Another option to consider is using your own DBMS for the server database. If you already have a
reliable DBMS which is already being backed up and provides the reliability you need such as MySQL
or Oracle we recommend you change the system DBMS to use your own managed DBMS rather than
maintain a separate one for JReport. For information on how to configure JReport to use a different
system DBMS, refer to Configure the server database.
Setting up and configuring a JReport Server Cluster
Before setting up a JReport Server Cluster, first you need to make the time difference between the
target computers that will join the cluster as small as possible (the time difference between the target
computers should be within one minute), and make sure all servers in the cluster will be set up on the
same architecture and operating system.
A JReport Server Cluster can be set up either during the JReport Server installation or after the servers
have been installed using the appropriate license key for cluster.
Creating a JReport Server Cluster during installation
It is recommended that you create a JReport Server Cluster during the installation of servers. This is
the easiest way for you to set up a cluster.
To create a JReport Server Cluster during installation:
1. Run the JReport Server installation file to install JReport Server with the Installation Wizard.
2. Specifies your User ID. In the License Key text field, use the cluster enabled license key.
3. When choosing the installation type, choose Custom Installation for Standalone Server. Then
specify the installation directory for JReport Server.
4. In the Service tab of the Configuration panel, check the Network Address At option and type in
the IP address of the server.
5. In the Cluster tab, specify a cluster name in the Cluster Name text field. You can either make the
server join an existing cluster or specify a new cluster name to build another cluster.
6. Uncheck the Disable Cluster option.
7. From the Load Balancer Type drop-down list, select the algorithm for load balancing clustered
servers.
8. Check the Cluster Scheduler Lease option to enable lease for the cluster, then set the active
count, valid time and check interval for the cluster scheduler lease. If you don't enable the lease
option, all clustered servers in the cluster will compete for a chance to trigger scheduled tasks
which could lower overall system throughput. Read main features for additional information.
9. Specify values for Cluster Storage History Number of Copies, Cluster Storage Realm Number of
Copies and Cluster Storage CRD Result Number of Copies. If you are using shared disk resources
for any of these directories you should set the value to 1. The default value is 2 which means
make one copy plus the original. This allows any one node to go down and the system will still be
able to find all resources. If you want to allow 2 simultaneous failures, set the number of copies to
3.
10. Specify the value for Cluster Memory Storage Number of Copies to set how many memory copies
will be shared in the cluster.
11. Check Notify via E-mail When a Server Is Down if you need to notify somebody via e-mail
when a server in the cluster is down, then in the E-mail Address text field, input the e-mail
addresses of the people to whom you want to send a notification e-mail.
12. Set the Properties, Realm, Resource, History, and Temporary Directories if necessary. If they are
not specified, default directories will be used.
13. Type the IP address or host name of the server in the Server's RMI Host text field, and type the
port number in the Server's RMI Port text field.
14. Go on with the installation steps to complete the installation.
15. Install another server you want to join the cluster and repeat the above steps to configure its
cluster settings.
Since JReport Cluster uses the same server DBMS, you need to make the system database in the
JDBC URL text field point to the same DBMS as the previous server. This requires that you replace
localhost with the IP address of the first cluster node that you installed, for example, jdbc:
derby://IP:1527/.
Creating a JReport Server Cluster after installation
After the servers have been installed using the appropriate license key for cluster, you can configure
the clustered servers either by using the JReport Administration page or the server.properties and
dbconfig.xml files.
Using the JReport Administration page
1. Start up the server that hasn't been enabled for cluster.
2. Log onto the JReport Administration page, and click Cluster > Configuration on the system
toolbar.
3. In the Cluster Name text field, specify a name for the cluster. You can either make the server join
an existing cluster or specify a new cluster name to build another cluster.
4. Check the Enable Cluster option.
5. Click Save to enable the cluster.
6. A cluster member ID will be generated automatically for the server. But if you need to modify it,
go to server.properties file located in <install_root>\bin and set the property cluster.member.
id.
7. Go to the JReport Administration > Data page, configure the databases to make sure they point to
the database that the server will use. For details, see Configuring the server database.
8. Restart the server you have enabled with cluster, then log onto the JReport Administration page,
go to the Cluster > Configuration panel.
9. From the Load Balancer Type drop-down list, select the algorithm for load balancing clustered
servers.
10. To enable lease for the cluster, check the Cluster Scheduler Lease option and set the active
count, valid time and check interval of the cluster scheduler lease respectively.
11. Specify values for Cluster Storage History Number of Copies, Cluster Storage Realm Number of
Copies, Cluster Storage CRD Result Number of Copies and Cluster Memory Storage Number of
Copies.
12. Check Notify via E-mail When a Server Is Down if you need to notify somebody via e-mail
when a server in the cluster is down, then in the E-mail Address text field, input the e-mail
addresses of the people to whom you want to send a notification e-mail.
13. Set the Properties, Realm, Resource, History, and Temporary Directories if necessary. If they are
not specified, default directories will be used.
14. In the Server's RMI Host text field, type the RMI IP address or host name of the clustered server.
15. In the Server's RMI Port text field, type the RMI port number of the clustered server.
16. Shut down the server.
17. Start up another server you want to join the cluster and repeat the above steps to configure its
cluster settings.
See also Cluster dialog for details about the cluster configuration options.
Using the server.properties and dbconfig.xml files
To set up a JReport Server Cluster using the server.properties and dbconfig.xml files, you need to
modify the server.properties file on each JReport Server. The process uses the following procedures:
1. In the server.properties file located in <install_root>\bin of each server, set the property
cluster.enabled=true.
2. Modify cluster.name in any server's server.properties file to specify the cluster name. If not
specified, it will take jreport-cluster as the default name.
3. In the server.properties file of each clustered server, modify the properties file as follows:
❍
❍
❍
cluster.member.id=(integer)
Specifies the member ID of the local server. The value of this property should be an integer no
less than 1.
server.rmi.host=localhost IP address
Specifies the RMI IP address or host name of the local server.
server.rmi.port=1129
Specifies the RMI port number of the local server.
4. Specify the paths of the directories on the physical disk, such as properties directory, realm
directory, resource root, history directory, and temporary files directory. The directories on each
clustered server should point to a different physical disk.
Add the following properties to the server.properties file:
❍
❍
❍
❍
resource.share.temp.dir=
Specifies the directories for storing temporary files.
resource.share.hist.dir=
Specifies the directories for storing all versions of report results in the cluster.
resource.share.realm.dir=
Specifies the directories of the realm files.
resource.share.properties.dir=
Specifies the directories of the properties files.
❍
resource.root=
Specifies the directories of the JReport demo reports.
5. Modify dbconfig.xml in each server's <install_root>\bin, and make sure that the system
database and realm database all server nodes use point to the same DBMS. For details, see
Configuring the server database.
Notes:
●
●
●
●
●
●
The databases that can be used as the server database in a JReport cluster must be able to support
the lock function, therefore, you cannot use HSQLDB as the server's database in a JReport cluster
because HSQLDB doesn't support the function.
If you have upgraded your JReport Server which is cluster enabled and uses HSQLDB as the server
database from versions prior to V9 to the current version, in order to make the server work normally,
you need to disable cluster on the server by adding the line server.cluster.enable=false to the server.
properties file.
If you set up a JReport cluster on one computer, you need to make sure that the settings of HTTP
Port, Administration Port, and Server's RMI Port on each cluster node be different from those on any
other nodes.
It is strongly recommended that you do not change the auto generated cluster member ID in a
JReport cluster, because distributed storage uses the member ID to recognize on which node the
physical files are stored.
If you want to use resources from folder real paths in JReport cluster, you should first specify a disk
in your file system and make sure that every node in the cluster has the same disk name mapping to
the same physical location.
Properties such as cluster.name, cluster.member.id, resource.share.properties.dir, resource.share.
realm.dir, resource.root, resource.share.hist.dir, resource.share.temp.dir, server.rmi.host, server.rmi.
port, cluster.enable, log.config.filename, log.config.update, and log.config.update.interval that
created in the server.properties file and their corresponding UI options on the JReport Administration
page need to be configured respectively for each cluster node. However, properties that are now
saved in the database should be configured for all the server nodes in the cluster. These properties
are:
❍
❍
All properties in the mailconfig.properties file in <install_root>\bin.
❍
All properties in the clusterWeight.properties file in the system database.
❍
●
The following properties listed before in the server.properties file: cluster.
enable_notify_server_down, cluster.notify_server_down_address, cluster.scheduler.lease.
active_count, cluster.scheduler.lease.check_interval, cluster.scheduler.lease.enabled, cluster.
scheduler.lease.valid_time, cluster.share_memory.node_number, cluster.storage.crd_result.
copy_number, cluster.storage.history.copy_number, cluster.storage.realm.copy_number,
loadbalance.custom_class, loadbalance.type, server.autocache.enabled, server.autocache.expired.
time, server.autocache.max.disk.usage, server.autocache.never.expire, server.completed.
max_count, server.crd.memory.usage, server.realm.active, server.security, server.version.from.
temp.
All properties in the LDAP configuration XML file LDAPProperties.xml in <install_root>
\properties.
No sub folders should be created under the realm directory because it may create a realm when
server is started.
●
●
●
To use the old result files in <reporthome>\history, install the new JReport Server to the same
directory with a new license key, overriding the existing program files.
In order to fax report results successfully in a cluster, you need to configure the fax settings for each
clustered server respectively.
If the content of the resource root directory jreports is removed, the Public Reports folder in the
resource tree will be empty.
Starting a JReport Server Cluster
To start a JReport Server Cluster, start the servers you have configured for the cluster one by one. If
you are using the default Derby DBMS, be sure to start Derby first by running startNetworkServer.bat/
sh in the <install_root>\derby\bin directory on the server containing the server DBMS.
Notes:
●
●
If you are using multiple IP address on a clustered server, you need to add -Djgroups.
bind_addr=IP address at which JReport cluster can work properly to its JRServer.bat file located in
<install_root>\bin to make sure the server can be started successfully.
If you have two JReport clusters with the same cluster name in a network segment, although the
two clusters are pointing to different databases, only the one started earlier can work successfully.
Example 1: Setting up a simple JReport Server Cluster
This example demonstrates how to configure a simple JReport Server Cluster by modifying the
configuration options on the JReport Administration page on each JReport Server.
Example description:
●
Set up a simple JReport Server Cluster using the JReport Administration page. Assume that JReport
Server Monitor has been installed on your computer.
●
The cluster consists of two copies of JReport Server on one computer.
●
The cluster uses one server DBMS.
●
The cluster uses shared directories for resources so no resource copies are required.
Take the following steps to set up the cluster:
1. Install the two JReport Servers respectively to C:\JReport\Server1 and C:\JReport\Server2
using the cluster enabled license key.
2. Launch the JReport Server installed to C:\JReport\Server2.
3. Log onto the JReport Administration page of Server2, click Configuration > Service on the
system toolbar, then set Port, Dashboard Port, and Administration Port respectively to 8885,
8884 and 8883 to make them different from those of Server1. You may use any port numbers
which are available on your system.
4. Click Cluster > Configuration on the system toolbar.
5. In the Configuration panel, specify a cluster name and check the Enable Cluster option, then
click Save to enable the cluster.
6. Restart the JReport Server installed to C:\JReport\Server2.
7. Log onto the JReport Administration page of Server2 using the administration port 8883 set in
Step 3 (http://localhost:8883).
8. Go to the Cluster > Configuration panel, leave the Load Balancer Type as Round Robin.
9. Check the Cluster Scheduler Lease option to enable lease for the cluster, then set the active
count, valid time and check interval for the cluster scheduler lease.
10. Change the Cluster Storage History, Realm and CRD Result Number of Copies to 1. We will just
use one resource directory.
11. Keep the default value 2 for Cluster Memory Storage Number of Copies, thus 2 memory copies will
be shared in the cluster.
12. Check the Notify via E-mail When a Server Is Down option, and in the E-mail Address text
field, input the e-mail addresses of the people to whom you want to send a notification e-mail.
13. Keep the default values for Properties Directory, Realm Directory, Resource Root, History
Directory and Temporary Files Directory.
14. Type the IP address or host name of Server2 in the Server's RMI Host text field, and type the port
number in the Server's RMI Port text field.
The port is the RMI port of the clustered server. The default port number is 1129. If there are two
or more JReport Servers started on one machine, the RMI port number of each clustered server
must be changed to a unique one, in order to avoid port conflicts.
In this example, the port number is changed to 1130, since the other server will use the default
port number 1129.
15. Click Save to accept all the changes, then shut down the server.
16. Edit C:\JReport\Server2\bin\dbconfig.xml and remove the lines with auto-start-derbyservice. We
only want Server1 to start the server DBMS since we will always use the Server1 database.
17. Launch the JReport Server installed to C:\JReport\Server1, log onto the JReport Administration
page (http://localhost:8889), then click Cluster > Configuration on the system toolbar.
18. Use the same cluster name as Server2, thus making Server1 join the existing cluster. Check the
Enable Cluster option, then click Save to enable the cluster.
19. Restart the JReport Server installed to C:\JReport\Server1, and then log onto the JReport
Administration page.
20. Go to the Cluster > Configuration panel, configure Server's RMI Host and Server's RMI Port.
Remember to keep Server's RMI Port to its default value 1129.
21. Upon finish, click Save to accept all settings and shut down Server1.
22. Copy rmi.auth in C:\JReport\Server1\bin to C:\JReport\Server2\bin. This allows RMI to be
authorized between the two systems.
23. Edit server.properties in C:\JReport\Server2\bin and remove cluster.member.id. It will be
recreated when you restart Server2 with a unique number.
24. Start the server Derby DBMS service by double-clicking the startNetworkServer.bat file in C:
\JReport\Server1\derby\bin.
25. Restart Server1 and Server2. It doesn't matter which one you started first.
26. Start JReport Server Monitor and check the cluster on the JReport Monitor page.
27. Access the JReport Console page of the first server using port 8888 as an administrator, and then
submit a scheduled task. In the Scheduled tab, you will see the newly scheduled task.
28. Log onto the JReport Administration page of the second server and create a new user Tom in the
Security > User panel. Access the JReport Console page of the second server using port 8883 as
Tom, and then submit another scheduled task.
Notes:
●
●
●
When you schedule to publish a report on a clustered server to disk, you should first specify a disk in
your file system and make sure that every node in the cluster has the same disk name mapping to
the same physical location. Then the publishing result will be directly saved to the disk you specify.
You can only view scheduled tasks that you have submitted.
From the JReport Console page of the clustered servers, you can only view completed tasks that you
have submitted.
●
If there are more than two clustered servers in the cluster, then after you shut down one server, all
the scheduled tasks running on this server will be run on other servers.
Example 2: Setting up a JReport Server Cluster for a production
environment
This example demonstrates how to set up a JReport Server Cluster on Unix/Linux by configuring the
cluster UI on each JReport Server. There will be three computers in the cluster. They are node1 (IP
address: 192.168.0.1), node2 (IP address: 192.168.0.2) and node3 (IP address: 192.168.0.3). All
JReport Servers in the cluster use Apache Derby as the server system database.
Take the following steps to set up the cluster:
1. Make the time difference between the target computers be within one minute.
2. Install JReport Server on each of the three nodes in directories /home/JReport/Server1, /home/
JReport/Server2 and /home/JReport/Server3 respectively using the appropriate license key for
the cluster, and install JReport Server Monitor on one of the nodes.
3. Launch the JReport Server installed to /home/JReport/Server1 on node1.
4. Log onto the JReport Administration page and click Cluster > Configuration on the system
toolbar. In the Configuration panel, specify a cluster name and check the Enable Cluster option,
then click Save to enable the cluster.
5. Restart the JReport Server on node1, and go to the JReport Administration page > Cluster >
Configuration panel.
6. Leave the Load Balancer Type as Round Robin.
7. Check the Cluster Scheduler Lease option to enable scheduler leases for the cluster, then set
the active count, valid time and check interval for the cluster scheduler lease respectively. The
defaults of 2 active schedules with a time of 300 seconds and check interval of 30 seconds are a
good starting point.
8. Keep the cluster storage history, realm and CRD result number of copies to 2. This means that
each resource will be copied to 2 of the 3 servers so there will be no single point of failure for the
resources.
9. Keep the default value 2 for Cluster Memory Storage Number of Copies, thus 2 memory copies will
be shared in the cluster.
10. Check the Notify via E-mail When a Server Is Down option, and in the E-mail Address text
field, input the e-mail addresses of the people to whom you want to send a notification e-mail.
11. Keep the default values for Properties Directory, Realm Directory, Resource Root, History
Directory and Temporary Files Directory.
12. In the Server's RMI Host text field, type the IP address or host name of Server1 as 192.168.0.1.
Type the port number in the Server's RMI Port text field as 1129.
13. Click Save to accept all the changes.
14. Go to the Data > System DB panel of Server1, in the Configuration tab, copy the URL in the URL
text field to a temporary file, and go to the Realm DB panel to copy the URL using the same way.
In order to use a JReport Server Cluster, all nodes in the cluster must use the same database. In
this case, all three nodes will use the database Server1 uses. This ensures that all servers in the
cluster share a single DBMS instance.
15. Shut down the server.
16. Launch the JReport Server installed to /home/JReport/Server2 on node2.
17. Log onto the JReport Administration page and click Cluster > Configuration on the system
toolbar. In the Configuration panel, use the same cluster name as Server1, thus making Server2
join the existing cluster. Check the Enable Cluster option, then click Save to enable the cluster.
18. Restart the JReport Server on node2. Go to the JReport Administration page > Data > System DB/
Realm DB, make the system database and realm database in the URL text field the same as those
of node1.
19. Go to the Cluster > Configuration panel.
20. In the Server's RMI Host text field, type the IP address or host name of Server2 as 192.168.0.2.
Type the port number in the Server's RMI Port text field as 1129.
21. Click Save to accept all the changes, then shut down the server.
22. Copy rmi.auth in /home/JReport/Server1/bin to /home/JReport/Server2/bin. This allows RMI
to be authorized between node1 and node2.
23. Launch the JReport Server installed to /home/JReport/Server3 on node3. Just like what we did
with node2, enable cluster and make node3 join the existing cluster too.
24. Restart the JReport Server on node3. Go to the JReport Administration page > Data > System DB/
Realm DB, make the system database and realm database in the URL text field the same as those
of node1.
25. Go to the Cluster > Configuration panel.
26. In the Server's RMI Host text field, type the IP address or host name of Server3 as 192.168.0.3.
Type the port number in the Server's RMI Port text field as 1129.
27. Click Save to accept all the changes, then shut down the server.
28. Just as we did with node2, copy rmi.auth in /home/JReport/Server1/bin to /home/JReport/
Server3/bin.
29. Start the server Derby DBMS service by running the startNetworkServer.sh file in /home/JReport/
Server1/derby/bin.
30. Launch the server on node1. In the Command Prompt window, you will see the following
information:
JReport Server is ready for service.
31. Similarly, launch the server on node2 and node3.
32. Start JReport Server Monitor and go to the JReport Monitor page to track the cluster.
Managing a JReport Server Cluster
The JReport Server Cluster page allows you to enable a cluster and configure and evaluate the
performance weight of the servers in the cluster. On this page, you can:
●
Enable and set up a cluster.
●
Configure the clustered servers.
●
Set the shared parameters of the clustered servers.
●
Evaluate the performance weight of the clustered servers.
On the JReport Administration page, you can also administer the servers in a cluster. In this section,
JReport Server Cluster administration is described in the following topics:
●
Configuring performance weight
●
Balancing the server load
●
Monitoring clustered servers
Configuring performance weight
If you have chosen the Weighted Min-load (loadbalance.type=2) algorithm for load balancing, you will
have to configure a performance weight for each clustered server in the cluster. The higher
performance weight you set to a clustered server, the higher chance it may get selected by the server
that has the active scheduler during load balancing.
To configure performance weight:
1. Start a clustered server in the cluster, on its JReport Administration page, click Cluster > Weight
to show the Weight panel.
2. Specify a weight value for each clustered server manually. Performance weight is a positive float
number.
3. Click OK to save the weight values.
4. If you want to test each clustered server's performance weight value at current time, specify a
catalog and a report that will be used for the testing in the Catalog and Report text fields and then
click the Test button.
The following are two examples for how Least Weighted Current Reports algorithm works:
Example 1 - when there are free servers:
Active Servers
ServerA ServerB
ServerC
Comments
Is local server
TRUE
FALSE
FALSE
Maximum concurrent reports
8
Unlimited
5
Number of currently running
reports
6
6
5
Performance weight
10
10
10
Weighted current reports
0.6
0.6
0.5
Is free
TRUE
TRUE
FALSE
Candidate servers
YES
YES
Select from free servers
Candidate servers
YES
YES
Select servers which have the least
Weighted current reports
Selected server
YES
Calculation
Current < MaxConcurrent, or
MaxConcurrent is unlimited
Local server has higher priority
Example 2 - when there are no free servers:
Active Servers
ServerA ServerB
ServerC
Is local server
TRUE
FALSE
FALSE
Maximum concurrent reports
10
10
10
Number of currently running
reports
10
10
10
Performance weight
4
5
8
2.5
2
1.25
Calculation
Weighted current reports
Comments
Is free
FALSE
FALSE
FALSE
Current < MaxConcurrent, or
MaxConcurrent is unlimited
Candidate servers
YES
YES
YES
Selects from all servers when all
servers are full
Candidate servers
YES
Select servers which have the least
Weighted current reports
Selected server
YES
Select ServerC
Balancing the server load
In a cluster environment, JReport Server provides a load balancing mechanism which enables the
server to work more effectively.
Load balancing process
1. When the time of a scheduled task arrives, active schedulers compete and the winner gets to
trigger the schedule.
2. The server that has the active scheduler selects a server in the cluster according to the load
balancing algorithm specified which can either be a built-in one or a customized one, and then
sends the task to the selected server.
Tip: You can also directly specify a server in a cluster to perform a scheduled task instead of using load
balancing. To do this, first make sure that the Identify Server Preference option is enabled in the Profile
dialog (Profile > Customize Server Preferences > Advanced > Identify Server Preference), and
then use the Specify a preferred server to run the task option in the General tab of the Schedule dialog
to specify a server manually.
Customized load balancing algorithm based on API
You can write your own load balancing algorithm based on the API included in JReport Server. Note
that if you create a load balancing algorithm with the API, it will take effect in place of other built-in
load balance algorithms you have set.
A demo DemoLoadBalancer.java has been provided to illustrate how to customize load balancing using
APIs. You can find it in <install_root>\help\samples\APICluster.
Assuming that you have several clustered servers.
Take the following steps:
1. Compile DemoLoadBalancer.java to generate the class file as follows (when compiling
DemoLoadBalancer.java, you need to add JRESServlets.jar to the class path):
javac -classpath <install_root>\lib\JRESServlets.jar DemoLoadBalancer.java
2. Add DemoLoadBalancer.class to the class path of setenv.bat in the ADDCLASSPATH variable.
3. Add the parameter -Dloadbalance.custom_class=DemoLoadBalancer to the server's startup file
JRServer.bat which locates in <install_root>\bin. For example:
"%JAVAHOME%\bin\java.exe" -Dloadbalance.custom_class=DemoLoadBalancer "-Dinstall.
root=%REPORTHOME%" ...
4. Launch JRServer.bat, the customized loadbalancer DemoLoadBalancer will then be applied.
5. Submit some tasks for running. You will now find that these tasks are allocated to the clustered
servers based on the DemoLoadBalancer code.
Reference: For more details, see the jet.server.api.cluster.LoadBalancer interface in JReport Javadoc
located in <install_root>\help\api.
Notes:
●
●
You can choose the load balancing type by setting the API method setLoadBalanceType() at jet.
server.api.admin.ClusterAdminService. For example, setting the API method as setLoadBalanceType
(0), setLoadBalanceType(1), setLoadBalanceType(2), and setLoadBalanceType(3) means respectively
the algorithm Least Current Reports (Min-load), Round Robin, Least Weighted Current Reports
(Weighted Min-load) and Random will be chosen.
For the load balancing algorithms: the server that holds the active scheduler selects from the servers
with the number of concurrently running reports less than maximum number first. However, if all
servers are full, it will select from all of them.
Monitoring clustered servers
JReport Server Monitor is a standalone web-based application used for monitoring the overall
performance of JReport Server. JReport Server Monitor should be used together with JReport Server.
JReport Server Monitor contains the following main features:
●
Inspects the status of JReport Server.
●
Shows server performance statistics in Graph/Text mode.
●
Maintains JReport Server.
●
Creates profiling reports: performance reports and statistics reports.
Before you can use JReport Server Monitor to monitor servers in a cluster, the following steps must be
taken:
1. Download and install JReport Server Monitor.
2. Modify the server.properties file in <monitor_install_root>\bin to configure the IP address and
port information of one clustered server.
3. Copy rmi.auth from <server_install_root>\bin of the clustered server whose IP address and
port information you modified in the last step to <monitor_install_root>\bin, or remove rmi.
auth from <server_install_root>\bin of this clustered server.
4. Start JReport Server.
5. Launch MonitorServer.bat in <monitor_install_root>\bin to start JReport Server Monitor.
6. Access JReport Server Monitor using http://monitorhost:monitorport (default 8848), or by
clicking the Monitor link on the JReport Administration page.
Note: The Monitor link will not be displayed on the JReport Administration page when the web.monitor.
link.enable property in the server.properties file in <server_install_root>\bin is set to false. You can
specify the monitor port by setting monitor.jmx.htmladaptor.port in server.properties.
Related topics:
●
Monitoring JReport Server
Dispatching RMI Server Pages requests in multiple server environment
You can dispatch RMI Server Pages requests in multiple server environment, which includes JReport clustered and non-clustered server
environment.
Sample solution: dispatch RMI Server Pages requests in clustered server environment
using customized dispatcher
This sample solution is to visit Server Pages JSPs remotely from WebSphere 7 to JReport Clustered Server using customized dispatcher.
See the below diagram for the structure:
You should be able to set up a similar service with any Java EE server by following the same procedure based on your preferred
application server documentation.
This demo dispatcher dispatches requests from different sessions to different JReport Servers according to Round-Robin algorithm. The
dispatcher has the Fail Over function, which will periodically check whether there is any unavailable server in the cluster. No request will
be dispatched to the unavailable server until the server is checked to be available again.
In general, the solution can be categorized into the following major steps:
1. Set up the server cluster.
2. Generate a WAR file containing Server Pages RMI JSP and dispatcher for WebSphere.
3. Deploy the WAR file to WebSphere.
4. Configure a clustered JReport Server.
In the following sections, we will explain clearly the exact operations you are expected to make in each of the main steps.
Setting up the server cluster
In this example we will set up two into the cluster using the Round-Robin algorithm.
192.168.0.1
192.168.0.2
Refer to Setting up and configuring a JReport Server Cluster for the specific steps of setting up JReport Server in a cluster.
Generating a WAR file containing Server Pages RMI JSP and dispatcher for WebSphere
1. Build a JReport Server WAR file as defined by makewar.xml for remote integration. The generated WAR file is saved to the default
directory <install_root>\bin\distribute.
makewar.bat buildRemoteWar -Djrs.remote.host=192.168.0.1 -Djrs.remote.rmiport=1129 -Djrs.rmi.auth_file=C:
\JReport\Server\bin\rmi.auth
2. Compile the dispatcher DemoRemoteDispatcher.java stored in <server_install_root>\help\samples\APICluster with
<server_install_root>\lib\JRESServlets.jar and <server_install_root>\lib\servlet.jar. The class file
DemoRemoteDispatcher.class and some other class files will be generated.
3. In the WAR file, drag the class files generated in step 2 to the remote.war\WEB-INF\classes\demodispath folder, assuming that this
folder has already been created in the WAR file.
Deploying the WAR file to WebSphere
1. Start IBM WebSphere 7.
2. Open Administrative Console. You can open Administrative Console by using the Start Menu, or by using the URL: http://
hostname:9060/ibm/console, where hostname is host name or IP address, and 9060 is the port number.
3. After successfully logging in, expand the Applications node, and then click Install New Application.
4. Click Browse to select your .war file. In the Context root field, type a context path such as /servlet/ ("/servlet" is also ok). Click
Next.
5. Do not check any option in this page, and then click Next.
6. Type RMI_Server Pages in the Application name field. DO NOT check the Precompile JavaServer Pages files option. Click Next.
7. Do not make any changes in the next two pages.
8. Click Finish in the Summary page. The installing process may take several minutes, wait until the process is completed.
9. After the installation process is completed, click Save directly to the master configuration. Then in the Save directly to the
master configuration dialog, click Save.
10. This step is to configure the dispatcher and cluster server. Go to WebSphere Admin Control to add some properties for this
dispatcher. Expand Servers, go through Server Types > WebSphere application servers > server1 > Process definition (in
the Server Infrastructure table > Java and Process Management) > Java Virtual Machine > Custom properties (in the Additional
Properties table).
Click the New button to add properties for our demo dispatcher com.jinfonet.dispatcher.configFile and jrs.remote.dispatcher.
Figure 1: Add property for com.jinfonet.dispatcher.configFile
Figure 2: Add property for jrs.remote.dispatcher
Note that the dispatcher DemoRemoteDispatcher.java will read the clustered server information in the hostport.properties file like
below:
rmiserver=192.168.0.1:1129
rmiserver=192.168.0.2:1130
...
11. If you have set up JReport Server in a cluster, you can append their host and port information to the above text file.
12. Click the Save link in the Messages table to save the changes, and then restart WebSphere 7.
Configuring the JReport Server Cluster
1. Make sure JReport Server has been started once in order that the server.properties file is generated.
2. Change server.properties file in <server_install_root>\bin as follows:
server.rmiserver.enable=true
server.rmiadminservice.enable=true
Then you can start JReport Server and access your Server Pages with a URL such as:
http://hostname:9080/remote
JReport Security System
In JReport Server, there are two types of security mechanisms. One is to deal with report resources,
and the other is to deal with web pages.
This chapter discusses these two mechanisms respectively:
●
Security for report resources
●
Security for accessing web pages
Security for report resources
In JReport Server, there are two types of security mechanisms for managing access and visibility of
report resources.
One is based on setting attributes of a report to control access and to control visibility of different
subsets of data based on user identity. This control is set during the design step, carried forward when
published, and handled at runtime without any special administrative action.
The other is based on administrative action in JReport Server to define the access rules for report
resources in the runtime environment. This involves registering JReport Server users, and setting
permissions on published Report resources.
This section discusses these two mechanisms respectively.
●
Report security system
●
Server security system
Report security system
This section demonstrates the control of access to reports and to different subsets of data by means of
defining report security. In general, report security can be classified into three groups: cached report
bursting, record level and column level. After applying report security, an end user will only see what
he or she is allowed to see.
The following topics explain the report security at each level in detail:
●
Cached report bursting
●
Record-level security and column-level security
●
Member-level security
Cached report bursting
Security in a report is a kind of privileged control. JReport supports cached report bursting which
creates a security mechanism for controlling access to the report. By defining which groups of data are
available to which users, groups, or roles, report results are created for each user, role and group.
When a user accesses the report result, JReport checks the user, group and role of the user and
merges the groups of data in the report the user is authorized to see and displays it to the user.
Cached report bursting is implemented with these security properties on the group panel: Cascade,
Grant, Groups, and Roles. The feature enables different users to view different data groups according
to their access privileges. It also applies to nested groups.
For detailed descriptions about setting up cached report bursting in reports, see Setting up a cached
report bursting policy for a report in the JReport Designer User's Guide.
This section focuses on how to view and schedule a report that has cached report bursting with JReport
Server.
●
Viewing a report with cached report bursting
●
Scheduling a report with cached report bursting
●
Example: e-mailing billing reports
Viewing a report with cached report bursting
Since the control of report access is not possible without a user ID, the significance of this function is
only apparent after reports have been published to JReport Server and users access it using their
JReport User ID (security identifier).
When a client views a report with cached report bursting in JReport Server, the corresponding groups
will be displayed according to the security identifier. You can also advanced run reports with cached
report bursting in different formats, including Page Report, HTML, PDF, TEXT, Excel, PS, XML and Rich
Text Format (this feature does not support the RST and Applet formats).
To view a report with cached report bursting in JReport Server, the report must first be published to
the server from JReport Designer. For example, if in JReport Designer, the security for a report that is
grouped by the Customer_Region field has been set as follows:
●
The user ID admin has the privilege to view the CA and MN groups of the report.
●
The user ID jennifer has the privilege to view the BC group of the report.
Then,
1. Access the JReport Console page via a web browser with the user ID admin.
2. Browse to the report that you are going to view.
3. Click the report name, and you will then be able to view the CA and MN groups of the report.
4. If you log onto JReport Server with the user ID jennifer, you will then only be able to view the BC
group.
Note: When designing the report in JReport Designer, if the Cascade property is set to be false, the
specified group will only display its group header and footer.
Scheduling a report with cached report bursting
You can schedule a report with cached report bursting as a normal report. However, there are some
differences between the formats in which the report is to be published.
Scheduling to HTML/Page Report Result to version
When you schedule a task to publish a report with cached report bursting to the HTML and/or Page
Report Result formats to the versioning system, the scheduled result depends on the mode which is
controlled by the property server.enable.cachedreportbursting in server.properties in <install_root>
\bin:
●
When server.enable.cachedreportbursting=true which is the default, JReport will create a report
result with the report data for all possible users. This allows the report to run with a single query to
the DBMS to create the report for all users in one pass. It is similar to report bursting, however,
report bursting does not support the Page Report Result format and it makes a separate physical
report result for each user and the administrator needs to manually restrict access to the results.
When a user views the report result using cached report bursting, JReport Server will use the
security identifier of the user to restrict access to the data in the report to the specific groups the
security identifier is allowed to view. The end result is the same as the bursting report in that the
user sees only his data, the advantage to the administrator is there is only one version result to
manage. Users can perform interactive actions on the scheduled page report result as on other page
report results, and the formulas, summaries and other similar data will be recalculated based on the
privileged data.
Note: If the report is cached report bursting and RLS/CLS mixed, then when other users other
than the user who did the scheduling view the scheduled HTML result, a blank page is displayed.
●
When server.enable.cachedreportbursting=false, the scheduled result only contains the data
that the user who did the scheduling is allowed to see. This is primarily for compatibility with pre-8.2
versions of JReport. In this case, "to page report result" is not supported.
Scheduling to e-mail
When you schedule a report with cached report bursting to publish it to e-mail, there is a slight
difference. JReport Server supports a multiple mail feature which enables sending the data results
directly to each user who is authorized to view the report.
Assuming that the catalog and the report have been published to JReport Server, and two users admin
and jennifer both have the permission to view the report. The following procedure shows how to
schedule a task on a report with cached report bursting to be published to e-mail.
1. Access the JReport Console page with user ID admin or jennifer.
2. Browse to the row that the report is in, put the mouse pointer over the report row and click the
Schedule button
on the floating toolbar.
3. In the General tab, select the report tab with cached report bursting.
4. In the Publish tab, switch to the To E-mail sub tab and then check This report has Cached
Report Bursting. E-mail the report to each specified user.
5. Type the subject and select the result format, then click Finish.
JReport Server will get the e-mail addresses from the user accounts, and then send the report result to
admin and jennifer, with the contents in accord with their access right to the report.
Note: Before publishing to e-mail, make sure you have input the e-mail addresses of the users when
configuring JReport Server. To do this:
1. Access the JReport Administration page, click Security on the system toolbar, and then select
User from the drop-down menu.
2. In the User panel, choose the user name that you want to edit in the User ID column, and then
click it. You can then type in the e-mail address of the user.
Scheduling to other formats
When scheduling a report with cached report bursting to other formats, the scheduled result only
contains the report data that the user who does the schedule is allowed to see. All users will see the
same data as the scheduling person.
Example: E-mailing billing reports
Sometimes, sending pertinent report data to corresponding mail recipients is required. JReport Server allows you to
send a scheduled report result to the e-mail addresses accordingly, based on the cached report bursting settings of
the report and the user information stored in JReport Server (e.g. e-mail address information). Therefore, each
recipient will only be able to view certain parts of the report data. However, using e-mail information of server users
is not reliable, since a user ID that is appropriate for the report doesn't always exist in JReport Server. In cases like
this, the mails will not be sent successfully. The best way to resolve this is to use an external e-mail information
source by implementing the UserMailList and UserMailListFactory API that JReport provides.
JReport provides two interfaces for you to retrieve user and e-mail information from a customized source:
●
●
jet.server.api.UserMailListFactory
Used to get the UserMailList instance implemented by the user.
jet.server.api.UserMailList
Used to get e-mail information from a customized source.
You can implement multiple classes of interface UserMailList. Each of them may refer to a particular report. By using
the getInstance() method in the jet.server.api.UserMailListFactory interface, you can get one implementation of the
UserMailList. For more information on these two interfaces, see JReport Server API Documentation.
The following is a simple example:
1. Here, there is a Customers table with customer names and their e-mail addresses, as illustrated below. You can
design a report using this table and others. Then apply cached report bursting for this report, so that later in
the server side, you can schedule the report and send pertinent data to different recipients saved in this
Customers table.
2. In JReport Designer, design a report and set cached report bursting for it. In this case, group the report data by
Customer Name, and then grant a formula FPageLevel to it. The content of the formula FPageLevel is as
follows:
@"Customer Name";
This means that only the records of the specified group will be shown at runtime when you enter with different
IDs -- Customer Name, in this example.
3. Then in the server side, implement the two interfaces to import the e-mail lists saved in the Customers table.
Specifically, implement the jet.server.api.UserMailListFactory interface. The getInstance() method should be
implemented in this interface to get an instance of jet.server.api.UserMailList. Take the following
implementation as a reference, where the implementing class name of the UserMailList interface is formatted as
"UserMailList_" + report + "_Impl", such as "UserMailList_InvoiceReport_cls_Impl".
import jet.server.api.*;
import jet.cs.util.*;
public class DemoUserMailListFactoryImpl implements UserMailListFactory {
public UserMailList getInstance(ServerInfo serverInfo) {
if (serverInfo == null) {
return null;
}
String rpt = null;
try {
rpt = serverInfo.getTaskProperties().getProperty(APIConst.TAG_REPORT);
} catch (RptServerException e) {
e.printStackTrace();
return null;
}
rpt = rpt.substring(rpt.lastIndexOf("/") + 1);
rpt = rpt.replace('.', '_');
rpt = rpt.replace(' ', '_');
String clsName = "UserMailList_" + rpt + "_Impl";
try {
UserMailList mailList = (UserMailList)Class.forName(clsName).newInstance();
return mailList;
} catch (InstantiationException e1) {
e1.printStackTrace();
} catch (IllegalAccessException e1) {
e1.printStackTrace();
} catch (ClassNotFoundException e1) {
e1.printStackTrace();
}
return null;
}
}
4. Then implement the jet.server.api.UserMailList interface, which gets the user and e-mail information from the
customized data source. The following implementation gets the e-mail list from the Customers table, which
contains Customer Name and Customer E-mail columns.
import jet.server.api.*;
import java.util.*;
import java.sql.*;
public class UserMailList_InvoiceReport_cls_Impl implements UserMailList {
public static Hashtable userEmails = new Hashtable();
private String curRealmName = "defaultRealm";
public UserMailList_InvoiceReport_cls_Impl() {
loadData();
}
private void loadData () {
try {
String jdbcDriver = "sun.jdbc.odbc.JdbcOdbcDriver";
DriverManager.registerDriver((Driver) Class.forName(jdbcDriver)
.newInstance());
Connection conn = DriverManager
.getConnection("jdbc:odbc:jinfonet4");
Statement stmt = conn.createStatement();
ResultSet rs = stmt.executeQuery("select * from Customers");
String userName = null;
String userEmail = null;
while(rs.next()) {
userName = rs.getString("Customer Name");
userEmail = rs.getString("Customer Email");
if (userEmail != null) {
userEmails.put(userName, userEmail);
}
}
} catch(Exception e) {
e.printStackTrace();
}
}
public java.util.Enumeration getAllMailAddresses(String realmName) {
if (realmName.equals(curRealmName)) {
return userEmails.elements();
} else {
return null;
}
}
public java.util.Enumeration getGroupMailAddresses (String realmName, String groupName) {
if (realmName.equals(curRealmName) && userEmails.containsKey(groupName)) {
Vector groupEmails = new Vector();
groupEmails.addElement(userEmails.get(groupName));
return groupEmails.elements() ;
} else {
return null;
}
}
public java.util.Enumeration getRoleMailAddresses (String realmName, String roleName) {
if (realmName.equals(curRealmName) && userEmails.containsKey(roleName)) {
Vector roleEmails = new Vector();
roleEmails.addElement(userEmails.get(roleName));
return roleEmails.elements() ;
} else {
return null;
}
}
public java.lang.String getMailAddress(String realmName, String userName) {
if (realmName.equals(curRealmName) && userEmails.containsKey(userName)) {
return (String)userEmails.get(userName);
} else {
return null;
}
}
}
5. Register the above classes to JReport Server before the server is started.
a. Add the parameter -Dcom.jinfonet.mailListFactory=UserMailListFactoryImplName to the command line/
batch file that starts JReport Server, where UserMailListFactoryImplName indicates the implementation of
the jet.server.api.UserMailListFactory interface.
In this case, the parameter should be -Dcom.jinfonet.mailListFactory=DemoUserMailListFactoryImpl.
b. Add the path of the implementation classes to the class path of the command line/batch file.
6. Start JReport Server and then publish the report and catalog.
7. Schedule the report, publish to e-mail, check the option This report has Cached Report Bursting. E-mail
the report to each specified user. Provide the necessary information and then submit the schedule.
The report will be processed and sent to the corresponding recipients with pertinent report data.
Record-level security and column-level security
The record-level security (RLS) and column-level security (CLS) of JReport Designer allow you to
control user access to different subsets of data and ensure that people only see what they are
supposed to see: record-level security allows you to define which records are to be revealed to any
given user, while column-level security allows you to define which report column is revealed to any
given user. This enables you to provide different users with accordingly different, but appropriate
contents. No matter to whom you need to provide information, a plant manager or thousands of
customers, JReport Designer allows you to control access to information according to your
requirements.
JReport Designer have two types of the security policies, one is a security policy based on a data
source connection (connection-scope security policy), and the other is a security policy based on a
single report (report-scope security policy).
●
●
Connection-scope security
You can build connection-scope security policies: where each security policy refers to a data source
connection in the catalog. If you want to implement the same security policy in a group of reports,
you can simply apply an existing security policy to the report, without having to repeatedly build
security information for each report. Both RLS and CLS can be connection-scope security.
Report-scope security
Additionally, record-level security can be of report scope, based on the security information file. That
is, you can use the security information file to set the security policies for a report. Report-scope
security policy doesn't support column-level security.
Record-level security can be applied simultaneously to both connection and report scopes. However, if
a report-scope security policy has already been applied to a report, it will override a connection-scope
security policy applied to the report. That is, report-scope security policies have a higher priority than
connection-scope security policies.
Running reports with record-level/column-level security
After setting up the security policy for a report in JReport Designer, you can then publish it to JReport
Server as normal. Then, when you log onto the server as different users, you will find that the security
settings are applied to the report. That is, different users will only see the data they are supposed to
see.
Note: The report designer defined users and roles may not be recognized by JReport Server. If your
security policies contain such users/roles, create these users and roles respectively in JReport Server,
and then in JReport Designer, synchronize the security information with JReport Server using the Merge
option.
See also Record-level and column-level security in the JReport Designer User's Guide for details about
how to set up record-level/column-level security policies and apply them to reports in JReport Designer.
Member-level security
Member-level security enables report designers to limit user access to the specific members of
dimensions in business/report cubes or of groups in business views.
The relationship between a user/role/group and the members of a dimension/group are classified into
these groups:
●
●
●
Allowed Set
The members of a dimension/group visible to a user/role/group, which are directly specified in the
user/role/group, excluding those inherited from the parent roles or groups.
Denied Set
The members of a dimension/group invisible to a user/role/group, which are directly specified in the
user/role/group, excluding those inherited from the parent roles or groups.
Unspecified members
The members of a dimension/group that are not specified in a user's allowed/denied Set or in the
inherited allowed/denied set from the user's parent roles/groups. The option is available to users
only.
A user/role/group can have its own allowed/denied set and inherit the allowed/denied sets from its
parent roles or groups. The parent allowed/denied sets will be calculated first and it is a recursive
process.
See also Member-level security in the JReport Designer User's Guide for more about member-level
security and how to set up the policy in JReport Designer.
Server security system
All of the report resources that are published to JReport Server are protected by the JReport Server
security system. This system is based on maintaining a registered set of users and setting permissions
on each resource for each user.
The User data model defines users, as well as their membership in groups and roles. By having groups
and roles, the system can apply permissions for a set of users with one transaction.
Resources are objects in resource trees or version tables, such as folders, resources and archive
versions. The permission settings control capability for a given user on the resource - if the resource is
visibile, if it can be read, written, deleted, executed, scheduled, and have its status updated.
JReport Server supports two ways to apply permissions to the the set of users. One is the default
system of setting permissions for users, groups and roles. The other is role-based definition, in which
permissions are defined on roles only, and users and groups are mapped to roles.
When JReport Server is performing runtime security checking for a given user, it will respect the
permissions settings and follow the access control rules when processing the service requests.
The JReport Server runtime security checking system is implemented based on a standard set of
Security Service method calls. The default implementation provided in JReport Server is based on the
data set of users and resources that is stored in JReport Server.
For integration with an existing application that already has a system for managing users and
permissions, JReport Server defines the Security Service as a Java interface and allows for an
application developer to supply a customized version to replace the default implementation. This allows
an existing application to provide a custom version of the Security Service that supports JReport Server
runtime security checking based on user data and permissions that are stored outside of JReport
Server. In this configuration, the JReport Server admin section for managing users and permissions is
not used.
JReport Server also can integrate with an existing application that uses an LDAP system for managing
user and group information. JReport Server can be configured to interact with the LDAP system so that
edit of information about users and groups can be done only in the LDAP system. Informaton about
permissions for resources is not part of the LDAP data model. That information continues to be
maintained by JReport Server.
Accessing user and permission data by database lookup on each service request may result in many
time-consuming IO operations. As a result, the performance of the server security system may be
lowered. In order to promote performance, a cache system exists just above the Security Service. The
cache system is used to store security objects including users, groups, roles and access control lists
obtained from making calls to the Security Service. This cached data will be used when the same
information is needed later.
The following is a diagram of the JReport Server security system structure:
Go through the following topics for details about the server security system:
●
Security system data model
●
Role based security
●
Security cache system
●
Customized implementation of the Security API
●
Using an LDAP server's security system
Security system data model
JReport Server provides a database to hold registered users and permissions on report resources. This
database will be used by the JReport Server Security Service to control access at runtime.
This diagram illustrates the data model used by the Security Service in JReport Server:
This shows the inherited relationship among User, Group and Role.
User data model
JReport Server defines these entities in the user model:
●
Realm
Realm is an abstract security concept, which hosts the resources and authentication entities on
JReport Server. There can be more than one realm on the server and each realm is independent from
others. The resources and authentication entities that reside in different realms are different.
At runtime, only one realm can be active and only the users and resources in the active realm are
accessible. A realm is identified by a unique name, which can contain any characters other than
forward slash (/) and backward slash (\).
The authentication entities consist of user accounts, group accounts and role accounts.
●
User
The user is the primary element of the database. It is a unique name that identifies a particular user
of JReport Server.
The JReport Server web pages are not accessible until a servlet session is established based on
verification and login of a registered JReport Server user. All activity done during the web session will
use that user identity when the Security Service is considering access privileges to report resources.
JReport Server comes with two built-in users, admin and guest. The built-in user accounts cannot be
deleted. The Admin user account can neither be deleted nor disabled.
●
●
Group
The principal group, which represents an organization of user accounts, is available for managing
users. Users or groups can be added into a group as its child members, and therefore inherit the
resource and folder permissions from the group.
Role
Users must have certain user rights and permissions in order to perform tasks on resources. Roles,
which represent an aggregate of permissions, help you to efficiently assign the appropriate user
rights and permissions to users. Assigning roles to users gives the users all of the user rights and
permissions of the roles to perform their jobs with. A role can also be assigned to other groups or
roles, and thus groups or roles can inherit the permissions of other roles. JReport Server comes with
two built-in role accounts, administrators and everyone. The built-in role accounts cannot be deleted.
The administrator role account can neither be deleted nor disabled.
Access control data model
Access control to report resources is based on this data model:
●
●
●
Permission
Permissions, associated with resources and folders, are the rules that are granted to users to control
their access to the resources and folders.
Privilege
Privilege is a mode for managing permissions. It can be used to manage different access permissions
unrelated with nodes. JReport Server offers these types of privileges for users: Publish and Advanced
Properties. Users that are granted the Publish privilege will be able to publish resources to JReport
Server, while users that have the privilege of Advanced Properties are allowed to view advanced
information of version properties such as catalog connections and report related resources.
Alias
JReport Server organizes file and directories into a Resource Tree. Aliases are used to provide
different "views" of a tree for different users to enter the Resource Tree. For example, you may set
an alias resource tree (based on the resource tree) for Tanya, so that she can only see the market
resource node and thus can directly walk into the report file she is interested in. In summary, an
alias is a combination of users and resource nodes.
To manage JReport Server's built-in security, you must be a member of the administrator role in order
to access the JReport Administration page.
Related topics:
●
Managing security
Role based security
In addition to the security system based on users, groups and roles, JReport Server also supports a
role based security system in which permissions are defined on roles only, and users and groups are
mapped to roles.
To switch to the role based security system, you can use either of the following two methods:
●
Check the Role Based Authorization option on the JReport Administration page > Configuration >
Advanced panel.
By default, the option is unchecked and the security mechanism of setting permissions for users,
groups and roles is applied. If the option is checked, the Permission Setting UI Displays option will be
hidden automatically, since it is used to control UI display and is of no use in the role based security
environment.
●
In the server.properties file, set server.rolebased.authorization to true.
In this case, the following three properties will not take effect since they control UI display of setting
user/group/role permissions:
server.ui.set_permissions.group
server.ui.set_permissions.role
server.ui.set_permissions.user
If the role based security system is used, in both the JReport Administration page (port 8889 by
default) and Console page (port 8888 by default), when you set permissions of a resource node, there
are only roles displayed. Role only based security is similar to Java EE security where the developer
assigns roles and during deployment users and groups can be mapped to the roles so if you are already
using Java EE security, this would be the best method.
Security cache system
The security cache system temporarily stores security objects such as users, roles, groups and ACLs. ACL, short for
Access Control List, is the core object of the security authorization system, and is in charge of storing and checking
principal permissions. When JReport Server requires information from the security system, it can fetch it from the
cache for better performance.
The cache system caches not only security objects for the built-in security system, but also those implemented by
the Security API from the external security system. It caches security information in the security data. If the
security service needs security information, it will fetch it from the security data. However, if the security data
cannot find the information, it will request it from the Security API, and then cache it in the cache system. When
the security information is modified in the security system, the Security API is invoked directly in order to modify
the security data.
Note: There is a special interface SecurityListener in the cache system, through which the cache is noted to update
the cached information. It is recommended that you invoke it when you access the external security system, so as
to synchronize security data between the cache system and the external security system.
The following focuses on the configuration and synchronization of the security cache system.
Configuring the security cache system
The security cache system enables you to define the maximum number of users, roles, groups and ACL objects that
can be cached. There are three ways in which you can customize the security cache system as explained below:
Configuring by editing the server.properties file
Edit the following four properties:
●
●
●
●
server.security.user.cache.size
This should be an integer value. Its value indicates the maximum number of user objects that the security cache
can store. The default value is 1000.
server.security.role.cache.size
This should be an integer value. Its value indicates the maximum number of role objects that the security cache
can store. The default value is 50.
server.security.group.cache.size
This should be an integer value. Its value indicates the maximum number of group objects that the security
cache can store. The default value is 50.
server.security.protection.cache.size
This should be an integer value. Its value indicates the maximum number of ACL objects that the security cache
can store. The default value is 100.
For instance,
●
If server.security.user.cache.size=1000, the cache can then store at most 1000 user objects.
●
If server.security.role.cache.size=100, the cache can then store 100 role objects.
●
If server.security.group.cache.size=100, the cache can then store 100 group objects.
●
If server.security.protection.cache.size=100, the cache can then store 100 ACL objects.
Configuring from the JReport Administration page
You must be a member of the administrator role in order to access the JReport Administration page.
1. Log onto the JReport Administration page, click Cache on the system toolbar, and then select Security Cache
from the drop-down menu.
2. In the Security Cache panel, four options are provided for specifying the cache size:
❍
❍
❍
❍
User Cache Size
The maximum number of user objects that the security cache can store. Should be an integer value.
Role Cache Size
The maximum number of role objects that the security cache can store. Should be an integer value.
Group Cache Size
The maximum number of group objects that the security cache can store. Should be an integer value.
Protection Cache Size
The maximum number of ACL objects that the security cache can store. Should be an integer value.
3. When done, click Save to apply the settings.
Configuring using the API method
Invoke the following methods in the API class jet.server.api.admin.cfg.ConfigurationAdvanced:
/**
* Set the security user cache's size
* Setting the size of the cache to zero or negative means closing the security user cache.
* @param size
*/
public void setSecurityUserCacheSize(int size);
/**
* Get the size of the security user cache
* @return the size of the security user cache
*/
public int getSecurityUserCacheSize();
/**
* Set the size of the security role cache
* Setting the size of the cache to zero or negative means closing the security role cache
* @param size
*/
public void setSecurityRoleCacheSize(int size);
/**
* Get the size of the security role cache
* @return the size of the security role cache
*/
public int getSecurityRoleCacheSize();
/**
* Set the size of the security group cache
* Setting the size of the cache to zero or negative means closing the security group cache
* @param size
*/
public void setSecurityGroupCacheSize(int size);
/**
* Get the size of the security group cache
* @return the size of the security group cache
*/
public int getSecurityGroupCacheSize();
/**
* Set the size of the security protection cache
* Setting the size of the cache to zero or negative means closing the security protection cache
* @param size<
*/
public void setSecurityProtectionCacheSize(int size);
/**
* Get the size of the security protection cache
* @return the size of the security protection cache
*/
public int getSecurityProectionCacheSize();
Synchronizing the security cache system
A synchronization system has been provided for synchronizing JReport Server's security system with your external
security systems. When the security cache system receives a security information modification event, it will then
fetch the security information from the API and update the cached information.
The following is a diagram of the synchronization system mechanism:
There are two ways to invoke the synchronization system. The first is to modify the security information on our
Server web UI (red line), and the second is to modify the external security system (blue line).
Customized implementation of the Security API
JReport Server provides a set of Security APIs which you can implement in order to build your
preferred security system. This section discusses the basic rules and implementation of the Security
API.
Partial Implementation of the Security API
The Security API can meet various requirements for seamlessly integrating the JReport security system
into an existing external security system.
By implementing all interfaces, you provide full functions to the JReport Server security system.
However, if you do not want to provide a complete security system to your JReport Server, but only to
use part of the functions available, you can achieve this by implementing the interfaces that meet your
requirements.
Here are some examples:
Example 1
Requirements: You only want to customize authentication and authorization.
The following interfaces are required to be implemented:
●
AuthenticationProvider
●
AuthorizationProvider
Example 2
Requirements: You want to customize authentication and users, while the JReport Server maintains
other functions of the security system.
The following interfaces are required to be implemented:
●
AuthenticationProvider
●
UserProvider
Example 3
Requirements: For CLS/RLS scenario, you must provide user/role information.
The following interfaces are required to be implemented:
●
AuthenticationProvider
●
UserProvider
●
RoleProvider
●
RoleUserRelationProvider
Implementing the Security API using an .xml file
You can specify a customized implementation of the Security API in a .xml file. The JReport Server
loads classes according to this file.
The file is customizedAPI.xml in <install_root>\bin. Specify the content in the .xml file as follows:
<?xml version="1.0" encoding="UTF-8"?>
<jreport-customized-api>
<security>
<authentication-provider>
com.customer.security.AuthenticationProviderImpl
</authentication-provider>
<authorization-provider>
com.customer.security.AuthorizationProviderImpl
</authorization-provider>
<user>
<provider>
com.customer.security.user.UserProviderImpl
</provider>
<permission-provider>
com.customer.security.user.UserPermissionProviderImpl
</permission-provider>
<privilege-provider>
com.customer.security.user.UserPrivilegeProviderImpl
</privilege-provider>
</user>
<group>
<provider>
com.customer.security.group.GroupProviderImpl
</provider>
<permission-provider>
com.customer.security.group.GroupPermissionProviderImpl
</permission-provider>
<privilege-provider>
com.customer.security.group.GroupPrivilegeProviderImpl
</privilege-provider>
</group>
<role>
<provider>
com.customer.security.role.RoleProviderImpl
</provider>
<permission-provider>
com.customer.security.role.RolePermissionProviderImpl
</permission-provider>
<privilege-provider>
com.customer.security.role.RolePrivilegeProviderImpl
</privilege-provider>
</role>
<relation>
<role-group>
com.customer.security.relation.RoleGroupRelationProviderImpl
</role-group>
<role-user>
com.customer.security.relation.RoleUserRelationProviderImpl
</role-user>
<group-user>
com.customer.security.relation.GroupUserRelationProviderImpl
</group-user>
</relation>
</security>
</jreport-customized-api>
Rules for applying customized Security API
The following are rules for applying customized Security API:
●
AuthenticationProvider is a core interface and must be implemented. It is first loaded when JReport
Server loads a customized Security API.
There are dependency relationships among some interfaces:
●
Interfaces PermissionProvider and PrivilegeProvider depend on the corresponding principal interface
provider. For example, the prerequisite for applying a customized UserPermissionProvider is that a
customized UserProvider has been applied.
Interface RelationProvider depends on both the corresponding principal interfaces. For example, the
prerequisite for applying a customized GroupUserRelationProvider is that a customized UserProvider
and GroupProvider have been applied.
●
If you partly implement the Security API, the JReport Server will automatically provide
implementation of some missed but required interfaces, in order to build an integrated security
system. Below are the rules:
❍
❍
●
If customized implementations of Providers have not been applied, the JReport Server will apply
built-in implementations of these Providers, including: AuthorizationProvider, UserProvider,
GroupProvider, RoleProvider, GroupUserRelationProvider, RoleGroupRelationProvider, and
RoleUserRelationProvider.
If you have applied a PermissionProvider or PrivilegeProvider, but not applied an
AuthorizationProvider, the JReport Server will apply the built-in implementation of the
AuthorizationProvider.
If you have applied an AuthorizationProvider, but not applied a PermissionProvider or
PrivilegeProvider, for example, UserPermissionProvider or UserPrivilegeProvider, the JReport Server
will not apply the built-in implementation of the PermissionProvider or PrivilegeProvider.
Notes:
●
For details about the Security API, see the jet.server.api.custom.security package in the JReport
Javadoc in <install_root>\help\api.
Demo references available in <install_root>\help\samples\APISecurity:
●
❍
❍
●
DemoAuthenticationProvider.java
Demo for implementation of the jet.server.api.custom.security.AuthenticationProvider interface.
DemoAuthorizationProvider.java
Demo for implementation of the jet.server.api.custom.security.AuthorizationProvider interface.
In V8, two new methods addSecurityListener() and isEnableEdit() are added into the API jet.server.
api.custom.security.AuthenticationProvider. If you have upgraded your JReport Server from V7 to a
higher version, and have applied customized implementation of AuthenticationProvider in V7, you
need implement the new methods in the API.
●
JReport Server provides the ability to use customized user authentication scheme by the
implementation of the two interfaces jet.server.api.custom.security.AuthenticationProvider and jet.
server.api.custom.security.AuthorizationProvider.
Using an LDAP server's security system
The server security system can run two modes in which you can use an LDAP server's security system.
The first is importing mode. In this mode, if you want to use the LDAP feature, you will have to import
the security information from an LDAP server. The second is non-importing mode. With this mode,
JReport Server can access an LDAP server and obtain LDAP security information directly without having
to import it.
Below is a diagram which illustrates these two working modes:
JReport Server can access an LDAP server using the LDAP implementation of the Security API (blue
line), and import security information from an LDAP server into the built-in security system (red line).
To use an LDAP server's security system, you should first enable JReport Server to adapt to a directory
server by configuring the settings in the Server tab (accessed by selecting Configuration > LDAP on
the JReport Administration page), making sure that the Enable LDAP Support option has been checked.
Notes:
●
●
Make sure that the Directory Manager DN is a user with prior LDAP Server permission, and who can
retrieve other LDAP users.
Make sure that the users and groups you want to query and import into JReport Server belong to the
organization you typed into the Distinguished Name field.
Pick a topic from the following to get more:
●
Examples of LDAP server configuration
●
SSL support in LDAP system
●
Limitations of LDAP support
●
Using LDAP server security information by importing
●
Using LDAP server security information via the LDAP implementation of the Security API
Examples of LDAP server configuration
Six directory servers are currently supported. These are:
●
Novell Directory Server
●
Microsoft Site Server
●
iPlanet Directory Server
●
Active Directory Advanced Server
●
Lotus Domino Server
●
OpenLDAP Directory Server
If you need access to a different directory server, contact your JReport Sales Representative. New
servers are frequently being added.
The following sections provide examples of settings which enable JReport Server to adapt to these
directory servers. They are as follows:
●
Example 1: Configuration for adapting to a Novell Directory Server
●
Example 2: Configuration for adapting to a Microsoft Site Server
●
Example 3: Configuration for adapting to an iPlanet Directory Server
●
Example 4: Configuration for adapting to the Active Directory Advanced Server
●
Example 5: Configuration for adapting to a Lotus Domino Server on NT
●
Example 6: Configuration for adapting to an OpenLDAP Directory Server
Example 1: Configuration for adapting to a Novell Directory Server
If you want to get all users and groups from the orgunit organizational unit, you should follow the steps
below to configure your Server tab on the JReport Administration page > Configuration > LDAP panel:
1. Select Novell Directory Server from the Select LDAP Server drop-down list, and then click Load
Settings. The settings of the Novell Directory Server will then be loaded.
2. Check the Enable LDAP Support checkbox, and input the following information:
❍
LDAP URL: ldap://IP address or host name of your Novell Directory Server (for example:
ldap://127.0.0.1)
❍
LDAP Server Port: 389
❍
Root Entry: o=the name of the root (for example: o=myorg)
❍
Directory Manager DN: cn=user name of the directory manager,o=context (for example:
cn=admin,o=context)
❍
Password: the password of the Directory Manager (for example: 1234)
❍
Encryption Type: None
❍
Import LDAP Groups to: Group
❍
User Schema
■
■
❍
Distinguished Name:ou=the name of the organization unit where you want to perform a
search for users (for example: ou=orgunit)
Filter: (&(cn=the filter criteria that you want to set )(objectclass=person)) (for example: (&
(cn=*)(objectclass=person)))
Group Schema
■
■
■
Distinguished Name: ou=the name of the organization unit that you want to perform a search
for groups (for example: ou=orgunit)
Filter: (&(cn=the filter criteria that you want to set )(objectclass=groupofuniquenames)) (for
example: (&(cn=*)(objectclass=groupofuniquenames)) )
Admin Group: The name of the group you want to add to the Admin group (for example:
develop)
3. You can test the connection settings by clicking the Test Connection button, get the query result
of the users specified in the option Filter by clicking the Query User button, and get the query
result of groups specified in the option Filter by clicking the Query Group button.
4. Click Save to save all settings.
Example 2: Configuration for adapting to a Microsoft Site Server
Follow the steps below to configure your Server tab on the JReport Administration page > Configuration
> LDAP panel. You can get all users from the members organizational unit and all groups from the
groups organizational unit.
1. Select Microsoft Site Server from the Select LDAP Server drop-down list, and then click Load
Settings. The settings of the Microsoft Site Server will be loaded.
2. Make sure that the Enable LDAP Support checkbox is selected, and input the following
information:
❍
LDAP URL: ldap://IP address or host name of your Microsoft site Server (for example:
ldap://127.0.0.1)
❍
LDAP Server Port: 1003
❍
Root Entry: o=test
❍
Directory Manager DN: cn=administrator,ou=members,o=test
❍
Password: test
❍
Encryption Type: None
❍
Import LDAP Groups to: Group
3. You can test connection settings by clicking the Test Connection button, get the query result of
users specified in the option Filter by clicking the Query User button, and get the query result of
groups specified in the option Filter by clicking the Query Group button.
4. Click Save to save all settings in this tab.
Example 3: Configuration for adapting to an iPlanet Directory Server
Follow the steps below to configure your Server tab on the JReport Administration page > Configuration
> LDAP panel. You can get all users in the people organizational unit and all groups in the groups
organizational unit.
1. Select iPlanet Directory Server from the Select LDAP Server drop-down list, and then click Load
Settings. The settings of iPlanet Directory Server will then be loaded.
2. Make sure that the Enable LDAP Support checkbox is selected, and input the following
information:
❍
LDAP URL: ldap://IP address of your iPlanet Directory Server
❍
LDAP Server Port: 389
❍
Root Entry: dc=mailbj,dc=jinfonet,dc=com
❍
Directory Manager DN: cn=directory manager
❍
Password: jinfonet
❍
Encryption Type: None
❍
Import LDAP Groups to: Group
3. You can test the connection settings by clicking the Test Connection button, get the query result
of users specified in the option Filter by clicking the Query User button, and get the query result
of groups specified in the option Filter by clicking the Group Query button.
4. Click Save to save all the settings in this tab.
Example 4: Configuration for adapting to the Active Directory Advanced Server
Follow the steps below to configure your Server tab on the JReport Administration page > Configuration
> LDAP panel. You can get all users and groups from the myorg organizational unit.
1. Select Win2000 Active Directory from the Select LDAP Server drop-down list, and then click
Load Settings. The settings are then cleared and you can input your information.
2. Make sure that the Enable LDAP Support checkbox is selected, and input the following
information:
❍
LDAP URL: ldap://IP address of your Windows 2000 Advanced Server
❍
LDAP Server Port: 389
❍
Root Entry: DC=testad,DC=local
❍
Directory Manager DN: CN=administrator,CN=Users,DC=testad,DC=local
❍
Password: 1234
❍
Encryption Type: None
❍
Import LDAP Groups to: Group
❍
User Schema
❍
■
User Attribute Name: cn
■
User Common Name: userPrincipalName
■
User Password: userPassword
■
Distinguished Name: ou=myorg
■
Filter: (&(cn=*)(objectclass=person))
Group Schema
■
Group Common Name: cn
■
Group Member Type: member
■
Distinguished Name: ou=myorg
■
Filter: (&(cn=*)(objectclass=group))
3. You can test the connection settings by clicking the Test Connection button, get the query result
of users specified in the option Filter by clicking the Query User button, and get the query result
of groups specified in the option Filter by clicking the Group Query button.
4. Click Save to save all settings in this tab.
Example 5: Configuration for adapting to a Lotus Domino Server on NT
By following the steps below to configure your Server tab on the JReport Administration page >
Configuration > LDAP panel, you can get all users and groups from the developer organization unit.
1. Select Lotus Domino on NT from the Select LDAP Server drop-down list, and then click Load
Settings. The settings are then cleared and you can input your information.
2. Make sure that the Enable LDAP Support checkbox is selected, and input the following
information:
❍
LDAP URL: ldap://IP address of your Lotus Domino Server
❍
LDAP Server Port: 389
❍
Root Entry:
❍
Directory Manager DN: cn=admin,o=jtotal
❍
Password: 123456
❍
Encryption Type: None
❍
Import LDAP Groups to: Group
❍
User Schema
❍
■
User Attribute Name: uid
■
User Common Name: cn
■
User Password: userPassword
■
Distinguished Name: ou=developer, o=jtotal
■
Filter: (&(cn=*)(objectclass=person))
Group Schema
■
Group Common Name: cn
■
Group Member Type: member
■
Distinguished Name:
■
Filter: (&(cn=*)(objectclass=groupofnames))
3. You can test the connection settings by clicking the Test Connection button, get the query result
of users specified in the option Filter by clicking the button Query User, and get the query result
of groups specified in the option Filter by clicking the Query Group button.
4. Click Save to save all settings in this tab.
Example 6: Configuration for adapting to an OpenLDAP Directory Server
By following the steps below to configure your Server tab on the JReport Administration page >
Configuration > LDAP panel, you can get all users and groups from the developer organization unit.
1. Select OpenLDAP Directory Server from the Select LDAP Server drop-down list, and then click
Load Settings. The settings are then cleared and you can input your information.
2. Make sure that the Enable LDAP Support checkbox is selected, and input the following
information:
❍
LDAP URL: ldap://IP address of your OpenLDAP Directory Server (for example:
ldap://127.0.0.1)
❍
LDAP Server Port: 389
❍
Root Entry: dc=openldap, dc=ldaptest
❍
Directory Manager DN: cn=Manager,dc=openldap,dc=ldaptest
❍
Password: 123456789
❍
Encryption Type: None
❍
Import LDAP Groups to: Group
❍
User Schema
■
User Attribute Name: uid
■
User Common Name: cn
■
User Password: userPassword
■
❍
Distinguished Name: ou=members
Filter: (&(uid=*)(objectclass=person))
Group Schema
■
Group Common Name: cn
■
Group Member Type: uniqueMember
■
Distinguished Name: ou=groups
■
Filter: (&(cn=*)(objectclass=groupofuniquenames))
■
Admin Group:
3. You can test the connection settings by clicking the Test Connection button, get the query result
of users specified in the option Filter by clicking the Query User button, and get the query result
of groups specified in the option Filter by clicking the Query Group button.
4. Click Save to save all settings in this tab.
SSL support in LDAP system
JReport Server's LDAP system supports SSL when connecting to an LDAP server for obtaining security
information.
Solving the wrong connection port type problem
JReport implements a method in the security system to solve the wrong connection port type problem.
The wrong connection port type problem in SSL protocol
If you use an SSL socket to connect to a server on a port that is not using SSL, or if you use a plain
socket to connect to a server's SSL socket, your program will hang. This is a characteristic of the SSL
protocol.
Method to avoid the wrong connection port type problem
Use a main thread to create a child thread for connecting to the LDAP server. The main thread can wait
on the child thread for a period of time-- the socket timeout time (This time can be set by users). If the
child thread creates an LDAP connection successfully, it will notify the main thread, and the program
will continue to run. However, if the child thread hangs due to using the wrong port type, the main
thread will only need to wait until the socket timeout time has been reached and can continue to run.
A Parameter setting in the method
There is an important parameter in this method: the socket timeout time. Since the connection time
varies with the user's network environment, it is better to set it in LDAPProperties.xml: modify the
element env-socketTime's value before the server is started. Its default value is 10, which means that
the socket timeout time is 10 seconds. You can modify this value according to your network
environment.
About SSL certificate store in JReport Server
Since JNDI uses the default SSL provider, the certificates will be checked by JSSE's default
TrustManager: X509TrustManager. If the TrustManager does not accept them, JReport Server will store
the SSL certificates into another key store file. This file is placed in <install_root>\properties
\LDAPKeyStore.keystore. The password to access the file is jinfonet. You can also use -D parameters
to specify another file and password. For instance, if you want to add the certificates into: C:\certs
\certs.keystore, and use the password test, you should add the following parameters to JReport
Server's startup file:
"-Djavax.net.ssl.trustStore= C:\certs\certs.keystore"
"-Djavax.net.ssl.trustStorePassword=test"
Note: The LDAP service provider uses JSSE for its SSL support. JSSE is available as part of Java 2
SDK, v1.4. As for earlier versions of the Java platform, you can turn to http://java.sun.com/products/
jsse for information. To use JSSE on a platform earlier than Java 2 SDK, v1.4, first install JSSE, and
then configure a JSSE provider either by updating the JAVA_HOME/lib/security/java.security file with
the provider or by adding the provider programmatically. Here JAVA_HOME refers to the directory
where the Java Runtime (JRE) software has been installed. Detailed steps can be found in the JSSE
Reference Guide.
Limitations of LDAP support
In the LDAP page, sessions are used to remember passwords and the status of the remember password
checkbox. Due to this, when the session exceeds the time limit, there are some limitations:
●
●
If the Load Settings button is clicked, and the session has expired, the user must log onto JReport
Server again. After that, the retained password will be lost.
If the session expires due to idling, when logging back onto JReport Server again, the retained
password will be lost.
Using LDAP server security information by importing
LDAP (Lightweight Directory Access Protocol) is a lightweight client-server protocol for accessing
directory services. With LDAP support, JReport Server enables you to import users/groups from
directory servers.
To import LDAP security server information, on the JReport Administration page, click Configuration >
LDAP > Import. In the Import tab, you can use LDAP users and groups in JReport Server by
importing them. In addition, in order to have the most current security information, you can
synchronize the security information from your local server with that of the LDAP server. To do this, on
the JReport Administration page, click Configuration > LDAP > Synchronize, where you can
predefine a role map for the imported LDAP users.
However, if you have checked Enable Auto-Import of Users from LDAP Server, users will automatically
be imported into JReport Server when they log in for the first time. The Enable LDAP Support and
Enable Auto-Import of Users from LDAP Server options in the Configuration > LDAP > Server tab work
together. The former determines whether an imported LDAP user can be used in JReport Server, and
the latter determines whether LDAP users can be imported automatically, as shown in the following
table:
=Checked;
=Unchecked
Enable
LDAP
Support
Local User
Enable
AutoImport of
Users
from
LDAP
Server
Can
be
used
YES
YES
YES
YES
Imported
LDAP User
YES
YES
NO
NO
NoneImported
LDAP User
YES
NO
NO
NO
Using LDAP server security information via the LDAP implementation of the Security
API
JReport Server can access an LDAP server directly using the LDAP Security API implementation. To achieve
this, you will need to turn on the LDAP security providers. There are three approaches to achieve this:
●
Configuring on the JReport Administration page
You must be a member of the administrators role in order to access the JReport Administration page. To
use the LDAP security providers, on the JReport Administration page, click Configuration > LDAP >
Server, then check Enable Direct Authentication to LDAP Server.
●
Configuring by API method
Invoke the following two methods in the interface ConfigurationLDAPServer:
/**
* Specifies whether or not the Server security system uses the LDAP providers.
* @return Returns true if using none imported LDAP support, otherwise returns false.
*/
public boolean isEnableNoneImportedLDAPSupport();
/**
* Specifies whether or not the Server security system uses none imported LDAP support.
* @param isEnableNoneImportedLDAPSupport Set this parameter to true if the Server
security system uses none imported LDAP support, otherwise set it to false.
*/
public void setEnableNoneImportedLDAPSupport (boolean isEnableNoneImportedLDAPSupport);
●
Editing the LDAP XML configuration file
Specify the following property in the LDAP XML configuration file:
<env-enableNoneImportedLDAPSupport>true</env-enableNoneImportedLDAPSupport>.
If the value is true, JReport Server security system will then use the LDAP providers. The default value of
this property is false.
Note: In order to use LDAP providers, a valid admin user is required to manage the JReport Server. The
following are rules for checking whether or not a user is an admin user:
●
●
Whether or not the user is a member of the LDAP admin group. The LDAP admin group is a configuration
option in the LDAP configuration XML file.
Whether or not the user is a member of the administrators role. The user can be granted the role by a
role map.
A user that meets one of these two rules is regarded as an admin user, and is thus allowed to access the
JReport Administration page.
Troubleshooting LDAP configuration
If you encountered any problems during LDAP configuration, refer to the following for help.
LDAP configuration failure resulting in re-login failure as an admin user
An admin user may fail to carry out LDAP configuration properly, and thus then cannot log onto the
JReport Administration page to manage the server. If this happens, you should follow the below steps:
1. Modify the property in the LDAP configuration XML file LDAPProperties.xml in <install_root>
\properties as follows to turn off the Enable Direct Authentication to LDAP Server option:
<env-enableNoneImportedLDAPSupport>false</env-enableNoneImportedLDAPSupport>
2. Restart JReport Server and log in as a built-in security admin user to correct the LDAP configuration.
Warning messages in the advent of incorrect LDAP configuration
Apart from the notes offered on the JReport Administration page > Configuration > LDAP panel, prompt
warning information is also provided in order to cope with incorrect LDAP configuration. The server system
will prompt warning messages in the following cases:
●
If you do not fill in the Admin Group field or specify an admin group.
●
If the admin group specified does not hold a user.
●
If the admin group specified does not exist in the LDAP server.
Security for accessing web pages
JReport Server provides a working web application as part of the product mix. This web application is
implemented as a group of JSP pages and servlets that run in a Java web server's servlet container.
JReport Server controls access to these JSP pages and servlets by requiring that a user be logged in to
a web session before the JSP pages or servlets will run.
JReport Server uses a security framework that allows for Single Sign On, so that a user only needs to
login to an existing application and not need to do another login to access JReport Server web pages.
●
Web page security
●
Single Sign On
Web page security
JReport Server provides a working set of JSP pages and servlets that form a web application to
schedule and run reports, and view results. This web application is only available to registered users
who identify themselves and log in to JReport Server.
JReport Server provides an administrative function where user information is maintained. An
administrator can register users with JReport Server, set passwords for them, and associate them with
groups and roles. This database of user information is used to validate the user name and password
that is used to log in to the web application.
Only logged-in users may access web pages
Only users who have logged in to the web application and created a session can access the web pages.
The session is a state that is maintained across multiple HTTP Requests using the Jave EE servlet
container's service to manage the session, and pass it into the JSP and servlet with each HTTP Request.
Each JSP page and servlet in the web application starts off with code that checks if the current HTTP
Request is from a user who is already logged in. If it is, the rest of the code executes because this user
is a known user. There may be more permissions checks within the code to control the specific request,
but the user is allowed to access the web page.
If the current HTTP Request is not from a user who is already logged in, then the code attempts to log
in the user using information available in the current HTTP Request.
If it is not possible to log in a user, then the JSP code recognizes that it is an Unauthorized request and
does not allow the rest of the code to execute. It may send back an Unauthorized message (HTTP 401)
to the browser or may do something else depending on configuration settings.
JRepor Server provides multiple ways for a user to log into the JReport web application.
●
Use an external service to take care of the login.
●
Use HTTP Authentication
●
Use a proprietary protocol based on query parameters in the URL.
The JReport Server web pages does the login process in the order shown, but this discussion will cover
them in reverse order because it is a better sequence to introduce the topics.
Using query parameters
When there is no current user logged in to the web session, JReport Server looks for specific query
parameters that it has designated as a way to pass in login credentials in the URL. This is a proprietary
login protocol developed to make it easy to identify a user by passing along the login request in the
URL along with the report operation request. A set of query parameters are defined that are used to
pass in the login credentials for a user.
If these query parameters exist, JReport Server will use their value and try to login the identified user
to the session. If the credentials are valid, then the user is logged in to the session, and the web page
can be accessed. Later HTTP Requests from that user will show that the user is logged in to the session.
Details about these parameters can be found in the javadoc entry for HttpUtil.checkLogin(), which is
the method that does the checking.
●
jrs.auth_id - value is the user name
●
jrs.auth_pwd - value is the password
●
jrs.authorization - value is string holding both user name and password encoded following a defined
process
Here is an example URL requesting the JSP page viewVersion.jsp with credentials passed in to log in
user "scott" with password "tiger".
http://localhost:8888/jinfonet/viewVersion.jsp?jrs.cmd=jrs.view_ver_def&jrs.
rst_version=1&jrs.ver_suff=.pdf&jrs.report=/SampleReports/InvoiceReport.cls?jrs.
auth_id=scott?jrs.auth_pwd=tiger
If no user is currently logged-in to the session, and the user "scott" with password "tiger" were a
registered JReport user, then the viewVersion.jsp page would run and the user scott would become
logged in to the session.
Using Http authentication
When there is no current user logged in to the web session, JReport Server looks at the HTTP Request
header for the Authorization field. This is an element that follows standard HTTP protocol for HTTP
Requests. Typically, it is filled in by the browser, based upon values entered by the user in a login
dialog form presented by the browser when it receives a Unauthorized Request (HTTP 401) response to
a URL request.
The browser responds to the Unauthorized Request response by presenting the user with the login
dialog, then submitting the original URL request again (automatically), but this time with the HTTP
Header having the Authorization field filled in with the user's credentials.
The browser remembers the user credentials and will send them in the HTTP Header Authorization for
all subsequent requests to the same URL.
The JSP pages of JReport Server look in the HTTP Header Authorization field for user credentials and if
found, will use them to validate the user. If the credentials validate a known user, that user is logged in
to the web session, and the page requested by the URL runs. Later HTTP Requests from that user will
show that the user is logged in.
As part of the HTTP Authentication protocol, JReport Server will respond to the browser when no user is
logged in to the session. It sends back the Unauthorized Request (HTTP 401) response, expecting that
the browser will gather credentials from the user and request the same HTTP Request again, with the
HTTP Header now containing the Authorization field. The JSP page will see the Authorization field on
the second time the request URL is sent.
HTTP Authentication is performed by this sequence of HTTP transmissions, and this processing by the
server and browser.
1. Browser sends URL as a HTTP Request to access a JSP page.
2. JReport Server does not see a logged-in user, and passes back an Unauthorized Request message
to the browser via an HTTP Response.
3. Browser prompts the user for login information.
4. Browser sends the URL again, this time with the HTTP Request header having the Authorization
field holding the user credentials.
5. JReport Server does not see a logged-in user, but sees the Authorization field in the HTTP Request
header, and attempts to login that user.
6. If JReport Server can validate the user credentials, the user is logged in to the session. If JReport
Server cannot validate the user credentials, it sends back another Unauthorized Request message
to the browser via an HTTP Response, and the cycle continues.
7. When the browser is asking the user for login information, the user may cancel the dialog. When
this happens, the browser displays a message to the user showing that the request was
unauthorized and does not send anything to JReport Server.
Note: The web page security system using HTTP Authentication and URL query parameters to pass in
credentials requires a secure network connection (SSL) to be effectively secure. Over a non secure
network, both the HTTP Authentication and URL query technique are lightweight security systems that
should not be used in a production system.
Using external service
When there is no current user logged in to the web session, JReport Server will make a call to an
external helper class method, asking it to return the User ID to use for the web session. If the method
call returns a User ID, JReport Server will validate that the User ID is registered with JReport Server
and if it is, it will log that user in.
This external helper class method is getExternalAuthorizedUser(). It is one of the methods defined in
the Java interface HttpExternalAuthorized. This Java interface defines a class that developers can
implement that will co-ordinate with the login protocol used by JSP pages in JReport Server as is
described here.
When developers implement HttpExternalAuthorized and deploy it, it is registered with JReport Server.
When this happens, it turns on what is called Single Sign On. This is a system that allows a local
application to control how to log a user in, and to co-ordinate with JReport Server JSP pages so they do
not enter into the HTTP Authentication dialog that would require a user to login to the system twice once for the application and once for JReport Server.
The implementation of getExternalAuthorizedUser() can identify the user that is logged in to the
application's web session and have JReport Server log that user in to the JReport Server web session
automatically.
If no user is currently logged in to the application session, then the call to getExternalAuthorizedUser()
will return a null. This tells JReport Server to work down the list of the other ways it has to login a user
based on information in the HTTP Request. It will look in the HTTP Header, then it will look in the URL
for query parameters. Eventually, if it fails to find any credentials it will recognize that the request for
the web page is an Unauthorized Request.
At this point, it calls the HttpExternalAuthorized method >handleUnAuthenticatedRequst(). This method
in the Java interface defines the function that can be implemented by developers to handle the case of
a web page receiving an Unauthorized Request.
The implementation can generate an HTTP Response that redirects the browser to the application's
login workflow and tell JReport Server to not engage in an HTTP Authentication dialog with the browser.
Validation of user during login
The explanation so far is about how login credentials are obtained to validate and login a user to the
web session.
When the user name and password is obtained, JReport Server will validate if the login credentials
match to a JReport Server user.
The built-in system for doing this looks at the information for the set of users that were registered with
JReport Server using the administrative tasks for managing users. It validates that the password is
correct for the given username based upon the information inside JReport Server's user database.
Application provides validation of user during login
JReport Server defines the AuthenticationProvider Java interface that developers can implement that
will do validation that a password is correct for the given username, using the application's user
database.
The developers can implement an instance of the AuthenticationProvider Java interface and register it
with JReport Server. Then this class and its method isValidUser() will be used to validate the user
instead of using the built-in validation method.
An example of an implementation of the AuthenticationProvider Java interface is available in the
sample source area in the file DemoAuthenticationProvider.java in <install_root>\help\samples
\APISecurity.
Limiting actions based on permissions
Once the JSP page is deemed accessible following the rules for login and validation, the JSP page is
allowed to run. The JSP page is run when an JReport user is correctly logged in to the web session.
However, it may be that the logged in user does not have permission to do the requested operation or
have rights for the target resource of the operation. The user may not have permission to run a report,
or the user may have permission to run a report, but not the specified one in the specified catalog.
This aspect of whether the user is authorized for the request is determined by JReport Server
evaluating the information in the user database that was added by an administrative task to manage
users and their permissions.
Application limits actions based on permissions
JReport Server defines the AuthorizationProvider Java interface that developers can implement that will
replace the built-in system for evaluating permissions and determining authorization.
The developers can implement an instance of the AuthorizationProvider Java interface and register it
with JReport Server. Then this class and its methods checkPrivilege() and isPermissionOK() will be used
to determine privilege instead of using the built-in authorization methods.
An example of an implementation of the AuthorizationProvider Java interface is available in the sample
source area in the file DemoAuthorizationProvider.java in <install_root>\help\samples
\APISecurity.
Demonstration and examples
There are two folders in the sample code area of the release that can be used to learn more about web
page security.
One contains a set of JSP pages that can be run to try out various styles of accessing a JSP page to see
how the login dynamics works. This is the folder <install_root>\help\samples\APISecurity
\LoginLogout. The entry point to the set of JSP pages is loginIndex.jsp. Read the comments in the JSP
page to understand how to run the demonstration.
The other contains two implementations of HttpExternalAuthorized and a set of JSP pages that can be
used to learn more about Single Sign On. This is the folder <install_root>\help\samples
\APISecurity\SingleSignOn. The entry point to the set of JSP pages is customIndex.jsp. Read the
comments in the java files and the JSP page to understand how to run the demonstration.
Single Sign On
JReport Server's web pages are built to work with an existing web application. In particular, it is possible to set up the web
server so that a user of the web site can login to an existing web application and have that login grant them access to JReport
web pages. This is called the Single Sign On feature.
This is done by developers implementing the class defined by the JReport Server Java interface HttpExternalAuthorized and
telling JReport Server to use that implementation.
The implementation can be aware of the application's technique for managing login state in the servlet session. This code can
tell JReport Server which user is logged in. The implementation can redirect the user to the application's login workflow if the
request is not from a logged in user.
This system gives the user one spot in the application to login. A successful login there will allow the user to run JReport
Server web pages without doing another login dialog.
JReport Server is told to use the local implementation of ExternalAuthorized in two ways.
●
Use the command line to define a system property that registers the class.
The system property jrs.httpExternalAuthorized is used to hold the name of the class that implements
HttpExternalAuthorized.
If the name of the class is SheldonsHttpExternalAuthorized.java, then change the script file that starts up JReport Server to
include the parameter string: -Djrs.httpExternalAuthorized=SheldonsHttpExternalAuthorized.
●
Use a Java API method call to register the class.
The Java API class HttpUserSessionManager has a method for setting the ExternalAuthrized object that JReport Server uses.
If the name of the package is com.mycorp.myHttpExternalAuthorized, then in a JSP page, connect to JReport Server, then
pass an instance of the class object for myHttpExtneralAuthorized as the parameter in the method HttpUserSessonManager.
setHttpExternalAuthorized().
<%@ page import="com.example.MyHttpExternalAuthorized" %>
// initialize and connect to JReport Server
initEnv(System.getProoperties());
HttpRptServer httpRptServer = HttpUtil.getHttpRptServer(request);
// set the HttpExternalAuthorized object used by JReport Server
httpRptServer.getHttpUserSessionManager().setHttpExternalAutorized(new myHttpExternalAuthorized());
There are examples of implementations of the ExternalAuthorized Java interface in the sample source files that come with
JReport Server. Look in the folder <install_root>\help\samples\APISecurity\SingleSignOn. Read the comments in the
source code for more information about Single Sign On and how the Java interface is used.
●
samples\APISecurity\SingleSignOn\CustomHttpExternalAuthorized.java
●
samples\APISecurity\SingleSignOn\com\example\MyExternalAuthorized.java
In that same SingleSignOn folder are several JSP pages that can be placed into the public_html\jinfonet folder and run as web
applications to exercise and demonstrate how Single Sign On works. The file customIndex.jsp is the entry point page. It has
comments inside it on how to run the demonstration.
Notes:
●
●
The set of application users does not need to be the same set of users that are registered in JReport Server. However, the
Single Sign On protocol does require that the application code identify the logged in user to JReport Server using a
registered JReport Server user name.
When the set of application users is different from the set of JReport Server users, then the application code for returning
the logged in user will need a system to map the applications user to a JReport Server user.
Configuring JReport Server
Once JReport Server has been installed and you have prepared the reporting environment, you can
then start it. However, you may find that JReport's default port number conflicts with an existing one in
your computer, or that you need to generate log files for analyzing a problem. In these cases, you will
need to configure your server. Before or while running the server, you can configure it according to
your systems.
The configuration work can be performed in two ways: via the JReport Server UI or via configuration
files. Some server UI options and properties in the configuration files are mapped and both function the
same way. For these types of settings, you can take either way to do the configuration. Appendix 4:
Mapping list of server UI options and properties details which server UI option are mapped to which
properties in the configuration files.
This chapter focuses on the following topics:
●
Configuration files
●
Performing administrative configuration work on UI
●
Configuring the server database
●
Configuring dynamic connections
●
Configuring another connection as a substitute for the catalog connection
●
Configuring connection pool
●
Configuring logs
●
Changing the server context path
Configuration files
The following table lists the files provided for configuration purpose and the corresponding server UIs
they are mapped to if applicable:
File
Mapped Server UI
Related Document
<install_root>\bin\classes.properties Apply old version Security API
(UserAuthenticator)
Description
-
-
<install_root>\bin
\ConnectionPoolConfig.properties
Engine connection pool
configuration
-
Configuring a connection pool
<install_root>\bin\datasource.xml
Connection mapping
configuration
-
Configuring the datasource.
xml file
<install_root>\bin\dbconfig.xml
Server DB configuration
JReport Administration
page > Data > System
DB/Realm DB/Profiling
DB > Configuration
Configuring the server
database in the dbconfig.xml
file
<install_root>\bin\dhtml.properties
Configuration for the Action
Task Manager
-
Action Task Manager > dhtml.
properties
<install_root>\bin\faxconfig.
properties
Configuration for sending fax
JReport Administration
page > Configuration >
Export > Fax
-
<install_root>\bin\jdbcdrivers.
properties
Configure the JDBC drivers that can be auto loaded
-
<install_root>\bin
\JdbcDriversConfig.properties
JDBC capability description
-
Configuring JdbcDriversConfig.
properties
<install_root>\bin\LogConfig.
properties
Configuration for log
JReport Administration
page > Configuration >
Log
Configuring logs
<install_root>\bin\mailconfig.
properties
Configuration for sending emails
JReport Administration
page > Configuration >
Export > E-mail
-
<install_root>\bin\server.list
Record relevant information
about the clustered servers,
including server name, server
IP address, server RMI port,
and server backup priority.
-
-
<install_root>\bin\server.properties
Comprehensive configuration
JReport Administration/
Console page
Appendix 1: Properties server.properties file
<install_root>\properties
\LDAPProperties.xml
Configuration for LDAP support
JReport Administration
page > Configuration >
LDAP > Server
-
Related topics:
●
Appendix 4: Mapping list of server UI options and properties
Performing administrative configuration work on UI
JReport Server UI can be accessed remotely from a client machine through a web browser such as
Internet Explorer. The JReport Administration page is available to administrators only. To perform
administrative configuration work as an administrator, first log onto the JReport Administration page.
On the JReport Administration page, these tabs are entry to different-purposed configuration panels:
●
Configuration - A comprehensive place for server configuration containing further-divided categories.
●
Security - Where you manage user accounts and permissions.
●
Profile - Where you define some initial settings for users' profiles.
●
Cluster - Where you configure and manage a JReport Server cluster.
●
Triggers - Where you create and manage triggers.
●
Data - Where you manage the server data.
●
Cube - Where you create and manage in-memory cubes for business views.
●
Cache - Where you create and manage the caches of data, reports, security objects and images.
Configuring the server database
There are three databases in JReport Server: system, realm, and profiling. The system database holds
resources of the global server scope, such as server.properties, global NLS, etc. The realm database
holds information of folders, nodes, versions, the security system, and the completed table. The
profiling database holds server runtime related information. The realm database is necessary in order
to run JReport Server. For best performance, you may want to configure the realm and profiling
databases separately, depending on your environment.
When you install JReport Server, a dbconfig.xml file is automatically created in the directory
<install_root>\bin. The database configuration information is stored in this configuration file. You
can configure your database by using the dbconfig.xml file.
These databases have been tested workable as the server database: Apache Derby, HSQLDB, MySQL,
Microsoft SQL Server, IBM DB2, Oracle, Sybase, and Informix.
This section presents the ways of configuring a server database for JReport Server in two different
environments. Also, you can specify a table space in the database configuration for JReport Server to
create tables in it.
●
Configuring the server database in a standalone environment
●
Configuring the server database when integrating with an application server
●
Creating tables in a specified table space
●
Schema support
●
Configuring JdbcDriversConfig.properties
Notes:
●
●
●
●
If you are using MySQL, make sure it is of version 5 or above.
If your server database uses DB2 and the charset is DBK, there will be the exception of encoding not
supported.
When setting SQL 2000 as the server database, the driver should use jtds.jar, otherwise the
scheduling feature cannot work.
ODBC is not supported.
Related topics:
●
Managing server data
Configuring the server database in a standalone environment
When JReport Server is running in a standalone environment, you can configure the database for it remotely on
the JReport Administration page. Also, since the server database configuration information is stored in the
dbconfig.xml file in the directory <install_root>\bin, you can also configure the server database in this file.
The following presents the two ways of configuring the server database in a standalone environment:
Configuring on the JReport Administration page
1. Log onto the JReport Administration page, click Data on the system toolbar and then select System DB,
Realm DB, or Profiling DB from the drop-down menu according to your requirement.
Note: The Profiling DB option is not shown by default on the drop-down menu. In order to make it
shown, you should set the server.profiling.enable property to true in the server.properties file in the
<install_root>\bin directory.
2. Select a realm if it is the Realm DB or Profiling DB panel.
3. In the Configuration tab, select a DBDriver from the Driver drop-down list and provide the driver class path
information in the Driver Class Location field.
Note: For HSQLDB and Derby databases, you do not need to specify the Driver Class Location. For all
other databases, you will have to provide the driver class path information unless it has already been
added to the class path of setenv.bat (setenv.sh on Unix) file during installation or by editing the
setenv.bat file.
4. Type a valid URL that can be used to establish a connection to the database. The valid format of the URL
should be provided by the DBDriver vendor.
5. Provide the user ID and password.
6. To test the connection, click Test. To update the database configuration and to apply the settings, click
Update and then restart the server to finalize the function.
Configuring in the dbconfig.xml file
In dbconfig.xml, you can configure the server database using one of two methods. One is to specify the URL,
driver, user and password individually. This method of configuration can be modified through the JReport
Administration page. For example:
<database name="systemtables/realmtables/profile">
<url>...</url>
<driver>...</driver>
<user>...</user>
<password>...</password>
</database>
Note: The <user> and <password> information is encrypted. The <user> and <password> tags will be replaced
by the <encrypt-sign> tag after JReport Server's startup as follows:
<encrypt-sign>enDkq7srM9cHhoUwzYXJ3NvcDIYk</encrypt-sign>
If you want to change user or password, delete the <encrypt-sign> tag and add the <user> and <password>
tags in the dbconfig.xml file.
The other is to use the <datasource> tag. For example:
<database name="systemtables/realmtables/profile">
<datasource>
jdbc://user:[email protected]:odbc:jreport-realmtables#driver=sun.jdbc.odbc.JdbcOdbcDriver
</datasource>
</database>
Here are two examples for your reference:
●
●
The following example is for Oracle. Modify the dbconfig.xml file as follows:
<?xml version="1.0" encoding="UTF-8"?>
<dbconfig>
<workspace name="systemRealm">
<database name="systemtables">
<url>jdbc:oracle:thin:@dbhost:1521:SystemDB</url>
<user>test</user>
<password>1234</password>
<driver>oracle.jdbc.OracleDriver</driver>
</database>
</workspace>
<workspace name="defaultRealm">
<database name="realmtables">
<url>jdbc:oracle:thin:@dbhost:1521:RealmDB</url>
<user>test</user>
<password>1234</password>
<driver>oracle.jdbc.OracleDriver</driver>
</database>
</workspace>
</dbconfig>
The following example is for a DataDirect driver. Modify the dbconfig.xml file as follows:
<?xml version="1.0" encoding="UTF-8"?>
<dbconfig>
<workspace name="systemRealm">
<database name="systemtables">
<url>
jdbc:datadirect:sqlserver://dbhost:1433;DatabaseName=SystemDB
</url>
<user>test</user>
<password>1234</password>
<driver>
com.ddtek.jdbc.sqlserver.SQLServerDriver
</driver>
<dbtype>Microsoft SQLServer</dbtype>
</database>
</workspace>
<workspace name="defaultRealm">
<database name="realmtables">
<url>
jdbc:datadirect:sqlserver://dbhost:1433;DatabaseName=RealmDB
</url>
<user>test</user>
<password>1234</password>
<driver>
com.ddtek.jdbc.sqlserver.SQLServerDriver
</driver>
<dbtype>Microsoft SQLServer</dbtype>
</database>
</workspace>
</dbconfig>
Notes:
●
●
●
Usually, JReport Server automatically creates database tables the first time it is started. The database
information that JReport Server uses is defined in the dbconfig.xml file. However, if the user ID defined in this
file does not have the permission to create tables in the database, JReport Server will fail to complete the
operation. In this case, you will need another user, such as the database administrator (who holds the relevant
permissions), to create a set of empty tables in the user's schema using the provided SQL files. These SQL files
can be found in <install_root>\script_files.
For MySql 5.0.xx, the letters in user name should all be lowercase.
Because of the compatibility between the third package Quartz used by JReport Server and the driver of
Oracle database, the Quartz package will throw exception when the class path of oracle database driver is
added into dbconfig.xml. To avoid this problem, when the JReport server works with Oracle database, do not
set database driver class path in dbconfig.xml.
Configuring the server database when integrating with an
application server
JReport Server supports connecting an RDBMS to access its system data via JDBC. The JDBC
configuration information is stored in the file dbconfig.xml in <install_root>\bin. You can create a
database connection according to this configuration file. Also, with the Java EE Data Source Support
feature, in a Java EE environment, JReport Server can get the predefined javax.sql.DataSource by JNDI
APIs.
Here, the term dsInfo is used to indicate where JReport Server can obtain the JDBC connection
information. It is a key-value pair. The name and value for dsInfo are defined as follows:
●
The name should be: jreport.datasource.<dbname>, where, <dbname> is JReport Server's inner
database name. It must be systemtables, realmtables, or profile. For example, the dsInfo name is
jreport.datasource.realmtables.
The value should be in the form of a URL. There are three protocols supported by JReport Server:
●
❍
file:///absolute_path_of_config_file
For example: file:///JReport/Server/bin/dbconfig.xml
❍
jdbc://[<jdbc-user:jdbc-password>@]<jdbc-url>[#<attribute-name=attribute-value>,]
For example: jdbc://user:[email protected]:odbc:jreport-realmtables#driver=sun.jdbc.odbc.
JdbcOdbcDriver
❍
jndi://[<jdbc-user:jdbc-passoword>@]datasource_name[#<attribute-name=attributevalue>,]
For example: jndi://jdbc/jreport-realmtables
The dsInfo can be specified in several places or levels, such as VM properties, ejb-jar.xml, web.xml and
<install_root>\bin\dbconfig.xml. The sequence to load the information is:
VM system environment > ejb-jar.xml (EAR mode) > web.xml (WAR mode) > dbconfig.xml.
Notes:
●
●
●
The jreport.ear file that JReport Server creates does not specify any Java EE information. By default
it will load from the dbconfig.xml file.
There is a limitation in WebSphere. JReport Server's dsInfo can be configured to the WEB-INF/web.
xml with JNDI name but not RESOURCE name. JBoss works fine for either one.
Do not use reporthome, @ or # in the JNDI name or Resource name.
The following shows specifying the dsInfo in web.xml, ejb-jar.xml, and dbconfig.xml respectively:
Specifying data source in web.xml (for the WAR mode)
When integrating the JReport Server in a WAR package, you can specify the dsInfo in the WEB-INF/web.
xml file using the <env-entry></env-entry> or <context-param></context-param> tags. However,
the use of the <env-entry></env-entry> tags is the recommended way since the tags are also
supported in ejb-jar.xml (if you call the Server API in your EJB).
The following is an example of specifying the dsInfo in WEB-INF/web.xml using the <env-entry></enventry> tags:
<web-app>
...
<env-entry>
<env-entry-name>jreport.datasource.realmtables</env-entry-name>
<env-entry-value>jndi://java:/resource-name</env-entry-value>
<env-entry-type>java.lang.String</env-entry-type>
</env-entry>
</web-app>
The following is an example of specifying the dsInfo in WEB-INF/web.xml using the <context-param></
context-param> tags:
<web-app>
<context-param>
<param-name>jreport.datasource.realmtables</param-name>
<param-value>jndi://datasource_name_which_is_predefined</param-value>
</context-param>
...
</web-app>
Specifying data source in ejb-jar.xml or web.xml (for the EAR mode)
When the JReport Server is used with APIs by EJBs, you can specify the dsInfo either in the file ejb-jar.
xml in /META-INF or web.xml in /WEB-INF.
For information about specifying a data source in the web.xml file, see section Specifying data source in
web.xml (for the WAR mode).
Note: If the dsInfo is stored in a Web module, you should add the JReport Server context listener to
the WEB-INF/web.xml file. Here is an example:
<web-app>
<listener>
<listener-class>
jet.server.servlets.JRServerContextListener
</listnener-class>
</listener>
...
</web-app>
You can specify the dsInfo in the META-INF/ejb-jar.xml file using the <env-entry></env-entry> tags.
For example, here is an EJB named firstEJB which creates the JReport Server instance. You can add the
<env-entry></env-entry> tags to the EJB's configuration file - META-INF/ejb-jar.xml as follows:
<ejb-jar>
<enterprise-beans>
<session>
<ejb-name>firstEJB</ejb-name>
...
<env-entry>
<env-entry-name>jreport.datasource.realmtables</env-entry-name>
<env-entry-value>jndi://java:/resource_name</env-entry-value>
<env-entry-type>java.lang.String</env-entry-type>
</env-entry>
</session>
...
</enterprise-beans>
...
</ejb-jar>
Specifying data source in dbconfig.xml
By default, JReport Server assumes that jreport.datasource.realmtables=file:///${rpthome}/bin/
dbconfig.xml. You can specify either a JDBC or JNDI data source using the <datasource></
datasource> tags in the dbconfig.xml file.
For details about configuring the JDBC data source, see Configuring the server database in a
standalone environment.
The following is an example of specifying the JNDI data source:
<?xml version="1.0" encoding="UTF-8"?>
<dbconfig>
<workspace name="systemRealm">
<database name="systemtables">
<datasource>jndi://datasource-name</datasource>
</database>
</workspace>
<workspace name="defaultRealm">
<database name="realmtables">
<datasource>jndi://datasource-name</datasource>
</database>
</workspace>
</dbconfig>
Creating tables in a specified table space
JReport Server supports creating tables in a user-specified table space in a database that supports
table spaces, such as DB2 and Oracle. A key-value pair tablespace is provided to specify a table space
into which JReport Server will create database tables. This key-value pair is then passed to JReport
Server through the JDBC configuration. JReport Server retrieves the table space information from the
JDBC (data source) configuration, and then creates tables in the specified table space.
Tablespace can be configured either in the dbconfig.xml file by using the <tablespace></tablespace>
tags, or in dsInfo by adding the attribute tablespace=table_space_name.
In dbconfig.xml
Add the <tablespace></tablespace> tags in the dbconfig.xml file as follows:
...
<workspace name="defaultRealm">
<database name="realmtables">
<driver classpath="...">jdbc_driver_name</driver>
<url>jdbc_url</url>
<user>jdbc_user</user>
<password>jdbc_password</password>
<tablespace>table_space_name</tablespace>
</database>
</workspace>
...
In dsInfo
Since the dsInfo supports JNDI and JDBC protocols, you can add the attribute
tablespace=table_space_name in the JNDI or JDBC statement.
●
jdbc://[<jdbc-user>:<jdbc-password>@]<jdbc-url>[#<attribute-name=attribute-value>,]
For example:
jdbc://user:[email protected]:odbc:jreport-realmtables#driver=sun.jdbc.odbc.
JdbcOdbcDriver,tablespace=myTablespace
●
jndi://[<jdbc-user>:<jdbc-password>@]<datasource-name>[#<attri-name=attri-value>,]
For example:
jndi://jdbc/jreport-realmtables#tablespace=myTablespace
Schema support
JReport Server supports DBMS schemas in order to work well with DBMSs that are currently supported
by JReport Server and that support schemas. Those DBMSs include Oracle, DB2, SQL Server, and
Sybase. You can specify schema information either in the dbconfig.xml file using the <schema></
schema> tags, or in dsInfo by adding the attribute schema=schema_name.
Note: For Sybase, the schema name must use capital letters, for example, ABCDE.
In dbconfig.xml
Add the <schema></schema> tags in the dbconfig.xml file as follows:
...
<workspace name="defaultRealm">
<database name="realmtables">
<driver classpath="...">jdbc_driver_name</driver>
<url>jdbc_url</url>
<user>jdbc_user</user>
<password>jdbc_password</password>
<schema>schema_name</schema>
</database>
</workspace>
...
In dsInfo
Since the dsInfo supports JNDI and JDBC protocols, you can add the attribute
schema=schema_name in the JNDI or JDBC statement. The JNDI approach is only available when
deploying JReport Server into a Java Application Server, not when it is running in standalone mode.
●
jdbc://[<jdbc-user>:<jdbc-password>@]<jdbc-url>[#<attribute-name=attribute-value>,]
For example:
jdbc://user:[email protected]:odbc:jreport-realmtables#driver=sun.jdbc.odbc.
JdbcOdbcDriver,schema=db2admin
●
jndi://[<jdbc-user>:<jdbc-password>@]<datasource-name>[#<attri-name=attri-value>,]
For example:
jndi://jdbc/jreport-realmtables#schema=db2admin
Configuring JdbcDriversConfig.properties
This document describes how to configure the file JdbcDriversConfig.properties in the <install_root>
\bin directory for better performance.
Limiting the size of the fetch data buffer
If you are using a database which supports the JDBC method Statement.setFetchSize(), you can
request the database retrieve a specified number of rows in each read instead of all rows which
minimizes memory usage which can improve performance. It can also avoid Java heap out of memory
errors when doing large queries. JReport provides a property setFetchSize in the JdbcDriversConfig.
properties file for you to do this.
The following is an example of setting the setFetchSize property in the JdbcDriversConfig.properties file
and detailed description of each property:
DriverName_D1 = MySQL-AB JDBC Driver
Vendor_D1 = MySql.com
Version_D1 = 3.0.8-stable ( $Date: 2003/05/19 00:57:19 $, $Revision: 1.27.2.18 $ )
setFetchSize_D1 = 5000
DriverName_[Name]
Database driver name that should be used to establish a connection. You can use connection.
getMetaData().getDriverName() to obtain the value.
Vendor_[Name]
The vendor of current JDBC driver. It is a string value.
Version_[Name]
The version of current JDBC driver. You can use connection.getMetaData().getDriverVersion() to obtain
the value.
setFetchSize_[Name]
The number of rows retrieved in each buffer from the database. It is an Integer value that should be
larger than 0 and less than or equal to getMaxRows(). The default value is different according to the
driver in use. You can refer to your own database driver specification.
_[Name]
It is a user-defined name used to mark a group of driver settings different from the other groups.
Specifying where to implement the maximum query run time and number of
records
In the JdbcDriversConfig.properties file, you can also specify where the properties, Maximum Rows and
Maximum Duration will be implemented, on JReport side or on the database side. For details about
usage of these two properties, see Limiting the query run time and number of records in the Queries
chapter of the JReport Designer User's Guide.
The following is an example of setting the two properties:
DriverName_D2 = Oracle JDBC driver
Vendor_D2 = Oracle
Version_D2 = 9.2.0.3.0
supportMaxRowPushDown_D2 = true
supportMaxDurPushDown_D2 = true
DriverName_[Name]
Database driver name that should be used to establish a connection. You can use connection.
getMetaData().getDriverName() to obtain the value.
Vendor_[Name]
The vendor of current JDBC driver. It is a string value.
Version_[Name]
The version of current JDBC driver. You can use connection.getMetaData().getDriverVersion() to obtain
the value.
SupportMaxRowPushDown_[Name]
Specifies where the property Maximum Rows will be implemented, on JReport side or on the database
side. By default, it is set to true, which means the property will take effect on the database side. If it is
set to false, the property will take effect on JReport side.
SupportMaxDurPushDown_[Name]
Specifies where the property Maximum Duration will be implemented, on JReport side or on the
database side. By default, it is set to true, which means the property will take effect on the database
side. If it is set to false, the property will take effect on JReport side.
_[Name]
It is a user-defined name used to mark a group of driver settings different from the other groups.
Canceling running query
If your JDBC driver support the Cancel Running Query feature and you want JReport to cancel the
running query used by a report in the database when you cancel the running task of the report, for
example, when you click the Cancel button on the report processing page of Page Report Studio, or
when you choose to stop a report running in background mode, configure the file JdbcDriversConfig.
properties as follows:
1. Add the JDBC driver you use into JdbcDriversConfig.properties if it is not listed there.
2. In the file JdbcDriversConfig.properties there is a line:
#supportCancelQueryStatement_D5=true
Remove the sign # and use your driver number instead of D5 to activate the feature.
3. Restart your JReport Server, then the next time, when you choose to cancel a running task, the
query used by the report will also be cancelled in the database, provided that the DBMS supports
this action.
Notes:
●
●
●
After you modified the JdbcDriversConfig.properties file, you need start the server to load the
changes.
If there are more than one group with the same group marking name, the last group will be adopted.
If the sign # is seen before "DriverName" of a group, or if setFetchSize is given a negative value, the
whole group will be disabled.
Configuring dynamic connections
A dynamic connection is a group of connection properties that can be used to override the original data source connections in a
catalog. The server administrator can modify some of the original catalog connection properties, and then save these modified
properties as a dynamic connection property. For a dynamic connection the administrator can define a database user mapping
table which is a table containing the columns: SID, database user, and database password.
JReport server manages the dynamic connections in the server system database.
When running a report or scheduling a report to run, if there are multiple dynamic connections available to the log-in user, the
user needs to select one. Then the server will pass the changed connection properties of the selected dynamic connection into the
report engine. The report engine will merge the changed properties with the other original catalog connection properties to setup
the database connection.
Creating a dynamic connection
1. On the JReport Administration page, click Configuration on the system toolbar and then select Dynamic Connections from
the drop-down menu.
2. In the Dynamic Connections panel, click the Add Dynamic Connection link. The Add Dynamic Connection dialog is
displayed.
3. Click Browse to select a catalog in the Select Catalog dialog.
4. From the Data Source Name drop-down list, select a data source available in the selected catalog.
5. Click Properties to expand the properties table. To change a property's value, first select the checkbox beside it, and then
enter a value in the text box or select a value from the drop-down list as required.
6. Click Add Database User Mapping to define the mapping relationship between SID and database user/password. A
mapping row will be added in the mapping table. From the SID drop-down list, select a user, role, or group name. Doubleclick in the text box of Database User and Database Password and you can then type in database user name and password.
Then click Test Connection to test whether the user name and password can connect to the database.
Within a dynamic connection, make sure that an SID is mapped to only one pair of database user and name.
7. Click OK to create the dynamic connection which will be listed in the Dynamic Connections panel.
See also Add Dynamic Connection dialog for additional information about options in the dialogs.
Managing dynamic connections
In the Dynamic Connections panel, the administrator can perform the following actions:
Searching for a dynamic connection
to start the search. The x
First select a search category from the drop-down list, then type the text in the text box and click
button in the text box is used to clear the input text. After the results are filtered, to return to the state before search, click x in
the text box.
There are the following search categories:
●
●
●
●
Catalog
Searches for catalogs.
Connection Name
Searches for connection names.
SID
Searches for SIDs.
Database User
Searches for database users.
For example, in order to find the dynamic connections which use the catalog SampleReprts.cat, you can select Catalog from the
search category drop-down list and input sam as the keyword. JReport will search for sam in the Catalog column and the dynamic
connections whose catalogs contain the text will be kept in the dynamic connection table.
Editing a dynamic connection
Click the connection name to open the Edit Dynamic Connection dialog, in which you can edit the properties of the dynamic
connection as you want.
Deleting dynamic connections
Select the checkboxes ahead of the dynamic connections and then click Delete. To delete all the dynamic connections at a time,
select the checkbox on the column header and then click Delete.
Applying dynamic connections
One user can have multiple dynamic connections for one catalog data source. When running a report, if there are multiple dynamic
connections for the log-in user:
●
●
●
For advanced run, the user needs to select a dynamic connection from the available ones.
For schedule run, if the selected dynamic connection cannot be found when running reports, then the first available dynamic
connection will be applied.
For direct run, link reports, API run, getting parameter values from the database, and getting filter values from the database,
the first available dynamic connection is applied automatically.
Connection priority
The priority from high to low is: dynamic connection > the connection specified in datasource.xml > catalog connection.
Related topics:
●
Dynamic connection API
Configuring another connection as a substitute for the
catalog connection
Normally, after a report has been created, it is fixed to a specific catalog connection. With the Java EE
Data Source Support feature, you can change to another runtime JDBC or JNDI data source to run
reports. This allows you to control the catalog data source connections in JReport Server to connect
dynamically to your production data sources.
This section focuses on the following:
●
Configuring the datasource.xml file
●
The connection priority
●
Reloading connection information from datasource.xml
●
Integrating JReport Server with your Java application server
●
Example 1: Using JNDI data source connections of WebLogic Server
●
Example 2: Using JNDI data source connections of JBoss server
Configuring the datasource.xml file
In order to enable you to conveniently set different connections in JReport Server, a configuration file,
datasource.xml, is provided with which you can define the connection to use at runtime by setting up
connection mapping information such as the JDBC driver, URL, or JNDI data source name, user and
password, depending on the data source your application uses.
The datasource.xml file is located in the <install_root>\bin directory. Change this file according to
the data source you want to use. Two types of connections are supported by JReport Server. They are
JNDI data source connection and JDBC connection.
There can be multiple <datasource></datasource> tags. Each pair will map one of the connections in
your catalog. You can define mapping connections for multiple connections for more than one catalog.
The catalog connection name should be unique in the datasource.xml file, otherwise the latter
<datasource> information will overwrite the previous ones.
The content of the datasource.xml file is as follows:
<?xml version="1.0" encoding="UTF-8"?>
<datasource-mapping>
<datasource>
<catalog-connection-name>Connection1</catalog-connection-name>
<connection-type>JNDI</connection-type>
<jndi-datasource>Sample</jndi-datasource>
</datasource>
<datasource>
<catalog-connection-name>Connection2</catalog-connection-name>
<connection-type>JDBC</connection-type>
<driver>sun.jdbc.odbc.JdbcOdbcDriver</driver>
<url>jdbc:odbc:jinfonet</url>
<user>Username</user>
<password>Password</password>
</datasource>
</datasource-mapping>
Element descriptions
●
●
●
●
catalog-connection-name
Specifies the name of the catalog connection that you want to substitute. Note that this is the
connection name that you can see in JReport Catalog Browser. A unique connection name in a
catalog is suggested.
connection-type
Specifies the connection type, which can be either JNDI or JDBC.
jndi-datasource
If you are using a JNDI data source, specify the JNDI data source name you defined in your Java
application server which you want to use as the substitute connection.
driver & url
If you are using a JDBC data source, specify the JDBC Driver and URL in these two attributes.
●
user & password
Specifies the user name and the password.
The <user> and <password> information is encrypted. The <user> and <password> tags will be
replaced by the <encrypt-sign> tag after JReport Server's startup as follows:
<encrypt-sign>enDkq7srM9cHhoUwzYXJ3NvcDIYk</encrypt-sign>
If you want to change user or password, delete the <encrypt-sign> tag and add the <user> and
<password> tags in the datasource.xml file.
You can choose whether to provide database user and password information for the JNDI connection,
using the <user> and <password> tags. If the user and password information is provided in this file,
it will be used to set up the connection regardless of the settings defined in your application server.
Otherwise, the settings defined in your application server will be used. Specially, for WebLogic users,
you should provide user name and password for WebLogic console instead of the database.
●
●
●
●
●
●
●
●
●
●
refresh-support-info
Optional. If it is true, JReport will get support information including reverse words, quote characters
etc from the driver each time fetching data from the database. If it is not set, the property will be
treated as false. It is recommended that you set this property to true when connecting to a different
database.
quote-character
Optional. Specifies the quote characters.
extra-characters
Optional. Specifies the extra characters.
date-format
Optional. Specifies the date format.
datetime-format
Optional. Specifies the datetime format.
time-format
Optional. Specifies the time format.
transaction-readonly
Optional. Specifies the transaction "read only" property. Possible value: default, Read only, or
Read&Write. Ignore other values.
transaction-mode
Optional. Specifies the transaction mode. Possible value: default, None, Read Uncommitted, Read
Committed, Repeatable Read, or Serializable. Ignore other values.
char-to-be-replaced
Optional. Specifies the characters that are to be replaced.
char-replaced-by
Optional. Specifies the characters used to replace the characters specified by char-to-be-replaced.
The connection priority
If you are using a catalog connection, datasource.xml, and at the same time, you have set new
connection information at runtime via the Server API/URL ((jrs.jdbc_driver, jrs.jdbc_url, jrs.db_user,
jrs.db_pswd), the priority of these three is as follows:
Runtime configuration of connection > datasource.xml > catalog connection
This means that if the approach with higher priority fails to get the connection, the one with the next
lower priority will be used.
The runtime configuration of connection includes the connection object and connection info (such as
url, driver, and user/pwd), and the connection object has higher priority than the connection info.
There are two ways of changing the connection by API at runtime, one is set the connection info by
specifying the data source name, which will only change the connection of the indicated data source;
the other is set the connection info without a specific data source name, which is regarded as a default
change and will change the connections that have not been changed by the previous way.
Assuming that the catalog has two databases named as data source 1 and data source 2, here are
some examples:
●
●
●
●
●
A user does not set datasource.xml, but sets the connection by API without specifying a data source
name. Both data source 1 and data source 2 will use the new setting.
A user does not set datasource.xml, but sets a new connection A by specifying the data source name
"data source 2". The result is: data source 1 has no change and data source 2 will use the connection
A.
A user does not set datasource.xml, but sets two connections by API, a new connection A by
specifying the data source name "data source 2" and a new connection B without specifying a data
source name. The result is: data source 1 will use the connection B and data source 2 the connection
A.
A user sets "data source 2" connection in datasource.xml and a new connection A by API by
specifying the data source name "data source 2". The result is: data source 1 has no change and
data source 2 will use connection A ignoring the setting in datasource.xml.
A user sets "data source 2" connection B in datasource.xml and a new connection A by API without
specifying the data source name. The result is: data source 1 will use the connection A and data
source 2 the connection B.
Reloading connection information from datasource.xml
After you have made changes to the datasource.xml file, you need to reload it in JReport Server. This
file can be reloaded using the following ways:
●
●
●
Call jet.server.api.admin.ConnectionInfoProviderService.reloadFile().
Log onto the JReport Administration page, go to Configuration > Connection panel, and then click
the Reload button.
Restart JReport Server.
Integrating JReport Server with your Java application server
After updating the datasource.xml file, you can integrate JReport Server with your application server.
If you are using a WAR file, make sure that the datasource.xml file is included in the WAR file. Before
making the JReport Server WAR file, in makewar.xml in the <install_root>\bin directory, add
<include name="datasource.xml" /> into the <zipfileset dir="${installroot}/bin"
prefix="workspace/bin"> section. Before you deploy the WAR file to a web server, make sure that
the datasource.xml file is included in the jreport.war/WEB-INF/lib/jrenv.jar/workspace/bin
directory.
If you are integrating JReport Server to an application using a non-JReport WAR file, usually you need
to specify the -Dreporthome parameter in the application server so that the application server can
locate and load the resources it needs. Since the datasource.xml already exists in the bin directory, you
do not need to do anything special for this file.
Example 1: Using JNDI data source connections of WebLogic
Server
Using WebLogic as an example, take the following steps:
1. Start WebLogic server, navigate to <YourProjectName> > Services > JDBC > Connection Pools. In
the Configuration tab, make sure that the connection you are going to use is there and correctly
set up.
2. Browse to <YourProjectName> > Services > JDBC > Data Sources. In the Configuration tab,
create a data source using the JNDI name MyJNDISample. Select the correct connection from the
Pool Name drop-down list.
3. Open datasource.xml in the <install_root>\bin directory and add:
<datasource-mapping>
<datasource>
<catalog-connection-name>ConnectionName</catalog-connection-name>
<connection-type>JNDI</connection-type>
<jndi-datasource>MyJNDISample</jndi-datasource>
<user>youruserid</user>
<password>yourpassword</password>
</datasource>
</datasource-mapping>
4. Build the JReport Server WAR file using the makewar utility in the <install_root>\bin directory.
5. Deploy JReport Server to WebLogic.
6. Run the report that uses this connection.
Example 2: Using JNDI data source connections of JBoss server
Using JBoss as an example, in this Example, DB2 is used, and JBoss is installed to D:\jboss-4.0.1,
take the following steps:
1. Copy the DB2 driver to D:\jboss-4.0.1\server\default\lib.
2. Create a db2-ds.xml file in D:\jboss-4.0.1\server\default\deploy, and add the following
content:
<?xml version="1.0" encoding="UTF-8"?>
<datasources>
<local-tx-datasource>
<jndi-name>DB2DataSource</jndi-name>
<connection-url>jdbc:db2://dbs-b/sample</connection-url>
<driver-class>com.ibm.db2.jdbc.net.DB2Driver</driver-class>
<user-name>db2admin</user-name>
<password>db2admin</password>
<min-pool-size>0</min-pool-size>
<metadata>
<type-mapping>DB2</type-mapping>
</metadata>
</local-tx-datasource>
</datasources>
3. Modify datasource.xml in <install_root>\bin. Make sure that the following are included:
<datasource-mapping>
<datasource>
<catalog-connection-name>ConnectionName</catalog-connection-name>
<connection-type>JNDI</connection-type>
<jndi-datasource>java:/DB2DataSource</jndi-datasource>
</datasource>
</datasource-mapping>
4. Build the JReport Server WAR file using the makewar.bat utility in the <install_root>\bin
directory.
5. Deploy JReport Server to JBoss.
6. Run the report that uses this connection.
Configuring connection pool
If you have used SQL or other similar tools to connect to a database and act on data, you probably
know that getting the connection and logging in is the part that takes the most time. A program can
spend several seconds every time it needs to establish a connection. To improve performance, JReport
Server supports caching a connection, so that it can be used each time the same user accesses the
same table. Cached connections are kept in the connection pool and can be used and re-used as
required. Therefore, JReport Server is freed from having to create the connection to the database,
leading to a considerable saving of time.
If you want to improve the performance of JReport Server, you can configure a connection pool using
the ConnectionPoolConfig.properties file in the directory <install_root>\bin. The following is an
example of the ConnectionPoolConfig.properties file and detailed description of each property in the file:
# jdbcpool configure information
URL1=jdbc:odbc:Jinfonet
Expire_URL1=0
IdleExpire_URL1=1
MaxCount_URL1=50
MaxShare_URL1=1
Attempt_URL1=1
Interval_URL1=0
URL1
JDBC URL that can establish a connection to your database. The URL contents are case sensitive.
This property is a must. You are required to give a value to it in order to establish a connection to the
database. The other six properties are optional. If no values are set to them, the default values will be
used.
"URL1" is an example of naming the URL. The name should start with the uppercase "URL". If you
change the name "URL1" to "URLxY", the "URL1" in the other property names should also be updated
to "URLxY", for example, "Expire_URL1" should be changed to "Expire_URLxY".
Expire_URL1
You can define how long in seconds it takes for an active connection to expire. The value for this
property by default is "0", which means that the active connection will not expire.
IdleExpire_URL1
You can define how long a free connection can be idle before it is closed. The connection will not be
released until the defined time has reached its limit. The value for this property by default is "1", which
means that the connection will be released after 1 second. If the value is "0", the connection will be
closed right after it starts idling.
MaxCount_URL1
The maximum number of connections based on the URL. The value for this property by default is "50".
Once the number of the connections reaches the maximum, a new connection will be blocked until a
free connection becomes available. Generally speaking, the fewer the connections, the better the
performance of JReport Server. If the value is set to "0", it means that there will be no limit on the
number of the connections.
MaxShare_URL1
The maximum number of requests in one connection that can be executed simultaneously. Once the
number of the requests reaches the maximum, a new connection will be created to connect to the
database. The value for this property by default is "1", which means that one request in one connection
can be executed simultaneously. The smaller the number of requests, the better the performance of
JReport Server. If the value is set to "0", it means that there will be no limit to the maximum number
of requests sharing one connection and that all the requests in one connection can be executed
simultaneously.
Since the property MaxShare_URL1 and MaxCount_URL1 are incompatible, you should make a balance
between these two properties to achieve the best performance of JReport Server.
Attempt_URL1
This property has a close relation to the property MaxCount_URL1. Once the number of the connections
reaches the maximum, a new connection will be blocked until a free connection becomes available. To
make the maximum use of the available connections in the pool, the property Attempt_URL1 allows
you to set how many times the engine will try to establish a new connection. The default value for this
property is "1", which means that the engine will only try once to create a new connection.
Interval_URL1
The interval the engine will wait for between attempts to create a new connection if a previous try has
failed. The default value for this property is "0", which means that the engine will start the next
attempt immediately. The unit of the property value is milliseconds.
Note: Administrators can access the JReport Administration page > Configuration > Connection Pool
panel for viewing connection information and for deleting unused connections.
Configuring logs
JReport provides a robust, flexible and configurable logging system, which is based on log4j version
1.2.8. JReport also supports versions of log4j version 1.2.8 to 1.3alpha7.
The logging system is used for obtaining meaningful and helpful JReport logging information in a
convenient way. It is easy to configure and manage. The following are the significant benefits of the
JReport logging system:
●
●
●
It is compatible with your application which is based on log4j.
It can be configured to output the logging information of different modules separately or to output
them all together.
It supports setting the trace and error type level separately.
Configuring logs
Log configuration tasks can be achieved in three ways. They are:
●
Using the JReport Administration page > Configuration > Log panel.
●
Using the LogConfig.properties file located in <install_root>\bin directory.
●
Using command options.
In comparison with earlier versions, the command options used for log configuration have undergone
a considerable change. The following are descriptions of these options:
Options
Description
-vDebug
Enables JReport Engine to output messages to a file and sets engine log file's
trace level to INFO and error level to WARN.
-vError
Enables JReport Engine to output messages to a file and sets engine log file's
trace level to OFF and error level to ERROR.
-logall
Sets all loggers' trace level to INFO and error level to WARN.
-log[:file Name]
Outputs JReport Engine messages to the file as specified and uses the -vDebug
level.
Note: Any settings made using the command options will override the trace and error type level
settings in the LogConfig.properties file.
Logging information using the trace and error type
The JReport logging system enables you to trace both normal and abnormal situations by using the
trace and error type. Trace is used for logging something expected or regular, such as tracing a
program workflow, logging runtime information and associated elements. Error is used for logging
something unexpected or irregular. For example, when a URL is unreachable, a file does not exist, or a
table cannot be found in a data source.
Trace type is divided into four levels, and is ordered according to the amount of information logged,
from the least to the most. These levels are OFF, OUTLINE, INFO, and TRIVIAL. Similarly, error type is
also divided into four levels, and is ordered according to the amount of information logged, from the
least to the most. These levels are OFF, FATAL, ERROR, and WARN. For detailed information about the
eight levels, see Log panel.
If you want the least amount of information to be logged, you can set trace level to OFF and error level
to ERROR. If you want the most amount of information to be logged, you can set trace level to TRIVIAL
and error level to WARN. Setting these to the highest level could affect system performance as well as
disk usage.
Customizing log file location
You can customize where to output logs in your local disk instead of using the default directory
<install_root>\logs.
By default, different log categories are output to different rolling files. For example, the Engine log is
output to Engine.log in the <install_root>\logs directory. If you want to customize the location of
the Engine log file, take the following steps:
1. Open the LogConfig.properties file located in the <install_root>\bin directory.
2. Modify the parameter log4j.appender.EngineRollingFile.File. Set its value to an absolute path with
a log file name, for example: C:\logs\Engine.log (on Windows) or /logs/Engine.log (on Linux/
Unix).
3. Save the LogConfig.properties file.
4. Restart JReport Server.
Configuration settings - effect on performance
The following are configuration properties which have an effect on server performance:
●
●
●
If the showTitle property is set to true in the LogConfig.properties file, the log file size will increase.
However, the effect on performance is negligible.
The levels of trace and error affect the amount of logging output. The higher the level, the more the
output. The settings for error level will have a negligible affect on performance but a high level for
trace may affect performance.
The use of the following conversion characters in ConversionPattern property results in the slow
generation of caller class or location information: %C, %F, %L and %M. Their use should be avoided
unless execution speed is not an issue. For information about the ConversionPattern property, see
comments in the LogConfig.properties file, which is located in the <install_root>\bin directory.
Changing the server context path
In some circumstances you may want to change the server context path for accessing JReport Server
console and running JReport reports. This section introduces how to do this in a standalone or an
integrated environment.
Changing standalone server context path
JReport has the following URL configuration for accessing JReport Server console and running JReport
reports in a standalone environment:
http://<hostname>:8888/jrserver
http://<hostname>:8888/jinfonet/index.jsp
http://<hostname>:8888/dhtmljsp/...
You may want to change the server context path as follows:
http://<hostname>:8888/jrp/jrserver
http://<hostname>:8888/jrp/jinfonet/index.jsp
http://<hostname>:8888/jrp/dhtmljsp/...
To do this:
1. Copy all contents in <install_root>\public_html to <install_root>\public_html\jrp.
2. Modify the following property values in server.properties in <install>\bin directory by adding "/
jrp":
web.design_servlet_path=/jrp/webreporting
web.dhtml_jsp_path=/jrp/dhtmljsp
web.dhtml_servlet_entry_path=/jrp/jrdhtml
web.dhtml_servlet_path=/jrp/dhtml
web.help_servlet_path=/jrp/help
web.jreport_servlet_path=/jrp/jrserver
web.skin.dir=/jrp/skin
3. Modify the value of jsp_path in redirect.properties in <install>\bin directory by adding "/jrp":
jsp_path=/jrp/jinfonet/
4. Modify mapping.properties in <install>\bin directory by adding "/jrp":
#
#
#
#
#
#
Map servlets to paths
Properties beginning with a . are extension properties, all other
properties are path properties
Format:
path or extension = servlet name
/jrp/jrserver=jrserver
/servlet/sendfile=sendfile
/jrp/dhtml=dhtml
/jrp/jrdhtml=jrdhtml
/jrp/help=help
.jsp=jspservlet
5. Start the server and access the server by the URLs:
http://localhost:8888/jrp/jrserver
http://localhost:8888/jrp/jinfonet/index.jsp
Run a report in Page Report Studio by the URL:
http://localhost:8888/jrp/dhtmljsp/dhtml.jsp?jrs.catalog=%2fSampleReports%
2fSampleReports.cat&jrs.report=%2fSampleReports%2fEmployeeInformation.cls
Changing integrated server context path
Supposing that all server resources are deployed to the context root folder jreport\ after deploying
JReport Server to an application server.
You can use the following URLs for accessing JReport Server service console and running JReport
reports in the integrated environment:
http://<hostname>:port/jreport/jinfonet/index.jsp
http://<hostname>:port/jreport/dhtmljsp/...
You may want to change the server context path as follows:
http://<hostname>:port/jreport/myjsp/jinfonet/index.jsp
http://<hostname>:port/jreport/myjsp/dhtmljsp/...
To do this:
1. Move index.htm and the following folders from jreport\ to jreport\myjsp\:
admin
dhtmljsp
images
javascript
jinfonet
skin
style
2. Create a file jrserver.properties in the \WEB-INF directory, add the skin and dhtmljsp properties
and provide the correct paths (the context root is excluded):
web.skin.dir=/myjsp/skin
web.dhtml_jsp_path=/myjsp/dhtmljsp
3. Access the server by the URL: http://<hostname>:port/jreport/myjsp/jinfonet/index.jsp
Run a report in Page Report Studio> by the URL:
http://<hostname>:port/jreport/myjsp/dhtmljsp/dhtml.jsp?jrs.catalog=%
2fSampleReports%2fSampleReports.cat&jrs.report=%2fSampleReports%
2fEmployeeInformation.cls
Managing JReport Server
The administration task in JReport Server consists of six major parts. They are management of
resources, versions, security, tasks, server data and cached report data. This chapter discusses these
task types in detail. After going through these topics, you will be able to manage your JReport Server
more effectively.
●
Managing resources
●
Managing versions
●
Managing security
●
Managing tasks
●
Managing server data
●
Managing cached report data
●
Managing in-memory cubes
Note: A JReport Live license for JReport Server is required in order to use web reports and all the
related functions, and a JDashboard license is required in order to use dashboards, library components,
and all the related features. If you would like a license please contact your Jinfonet Software account
manager to obtain a license.
Managing resources
Resources on JReport Server are organized into a tree structure called the Resource Tree. Only the
resources that are organized in the resource tree can be accessed and queried by a client.
You can perform basic resource tasks, such as publishing, deleting, getting resources from a real path,
and more advanced tasks, such as changing resource and folder properties. Moreover, you can also
manage the versions and secure your resources. Detailed information is available in sections Managing versions and Managing security.
Note: Catalogs are by default not displayed in the server resource tree on the JReport Console page.
In order to perform operations on catalogs published from outside of JReport Server on the JReport
Console page, you need to enable them to be displayed first by setting the web.page.option.
show_catalog property to true in the server.properties file.
This section includes the following topics:
●
Publishing resources
●
Converting reports of earlier versions into current version
●
Getting and using resources from a real path
●
Customizing TTF font location for resources
●
Working with custom fields
●
Changing resource and folder properties
●
Linking resources and catalogs
●
Deleting resources
Publishing resources
Before you can perform any tasks on JReport Server, you first need to have your resources published and organized. The resources are
reports, library components, catalogs, and folders.
The JReport Server resource tree contains four built-in folders: My Components and Public Components are used to store library
components with catalogs, while My Reports and Public Reports store reports with catalogs.
There are three ways of publishing resources:
●
Publishing resources from JReport Designer
●
Publishing resources from a local computer
●
Publishing resources from a remote computer
Note: After resources have been delivered to JReport Server, you may find that the publish time shown on the server UI is different
from the client time. That is because the publish time takes the server time instead of the client time.
Publishing resources from JReport Designer
You can directly publish your reports, library components, or catalogs from JReport Designer to JReport Server. For detailed information,
see the topic Publishing resources remotely in the JReport Designer User's Guide.
Publishing resources from a local computer
You can publish these types of resources from a local computer. They are reports, library components, catalogs, and folders.
To publish resources from a local computer:
1. Do either of the following to access the Publish to Local Server dialog:
❍
❍
For administrators, on the JReport Administration page, click Resources on the system toolbar and select Resources from the
drop-down menu. In the Resources panel, browse to the folder where you want to publish the resources, then click the Publish
to Local Server link.
For end users, on the JReport Console > Resources page, browse to the folder in which to publish the resources, then on the task
bar of the Resources page, click Publish > To Local Server.
The Publish to Local Server dialog is then displayed.
2. Select a type from the Resource Type drop-down list.
3. Specify properties for the to-be-published resources as required.
❍
If the Page Report or Web Report resource type is selected:
1. In the From File text field, specify the report you want to publish with its full path.
2. In the Resource Node Name field, specify a name for the report. This name is required and is used as the display name of
the report in the server resource tree.
3. Type a brief description to describe the report in the Resource Description field.
4. From the Status drop-down list, select the status of the report.
5. Specify values of the custom fields for the report if there are custom fields.
6. Click the Browse button to specify a font directory for the report.
7. Click the Browse button to specify a style directory for the report.
8. Click the Browse button to specify a geographic information directory for the report.
❍
If the Catalog resource type is selected:
1. In the From File text field, specify the catalog you want to publish with its full path.
2. In the Resource Node Name field, specify a name for the catalog. This name is required and is used as the display name of
the catalog in the server resource tree.
3. Type a brief description to describe the catalog in the Resource Description field.
4. Specify values of the custom fields for the catalog if there are custom fields.
❍
If the Component resource type is selected,
1. In the From File text field, specify the library component you want to publish with its full path.
2. In the Resource Node Name field, specify a name for the library component. This name is required and is used as the display
name of the library component in the server resource tree.
3. Type a brief description to describe the library component in the Resource Description field.
4. Specify values of the custom fields for the library component if there are custom fields.
5. Click the Browse button to specify a font directory for the library component.
6. Click the Browse button to specify a style directory for the library component.
7. Click the Browse button to specify a geographic information directory for the library component.
❍
If the Folder resource type is selected:
1. In the Resource Node Name field, specify a name for the folder. This name is required and is used as the display name of
the folder in the server resource tree.
2. Type a brief description to describe the folder in the Resource Description field.
3. In the Resource Real Path text field, type a local disk path as the real path of the folder. If you want to enable getting
resources from the real path, check Enable Resources from Real Paths. The local disk resources will be mapped into the
resource node of the folder in the server resource tree and the server will be able to always get resources and updates from
the real path. For details, see Getting and using resources from a real path.
If this step is skipped, the publish job will simply create a new blank directory node in the server resource tree.
4. Specify values of the custom fields for the folder if there are custom fields.
❍
If the Folder with Contents resource type is selected:
1. Click the Browse button next to the From Folder text field to specify the folder where the resources you want to publish are
saved.
2. In the Resource Node Name field, specify a name for the folder. This name is required and is used as the display name of
the folder in the server resource tree.
3. Type a brief description to describe the folder in the Resource Description field.
4. In the Resource Real Path text field, type a local disk path as the real path of the folder. If you want to enable getting
resources from the real path, check Enable Resources from Real Paths. The local disk resources will be mapped into the
resource node of the folder in the server resource tree and the server will be able to always get resources and updates from
the real path.
5. Specify values of the custom fields for the folder if there are custom fields.
6. Click the Browse button to specify a font directory for the resources.
7. Click the Browse button to specify a style directory for the resources.
8. Click the Browse button to specify a geographic information directory for the resources.
9. If you want to use Advanced Publish, click the Advanced Publish button. All resources contained within the specified folder
will then be displayed. Check the resources you want to publish and specify the properties for each resource as required.
❍
If the Catalogs, Reports and Folders in Folder or Catalogs and Reports in Folder resource type is selected:
1. Click the Browse button next to the From Folder text field to specify the folder where the resources you want to publish are
saved.
2. Click the Browse button to specify a font directory for the resources.
3. Click the Browse button to specify a style directory for the resources.
4. Click the Browse button to specify a geographic information directory for the resources.
5. If you want to use Advanced Publish, click the Advanced Publish button. All resources contained within the specified folder
will then be displayed. Check the resources you want to publish and specify the properties for each resource as required.
4. If the resources you specify to publish contain reports created in earlier versions, check Automatically Convert Old Report
Schemas, the reports will then be automatically converted into current version JReport reports when publishing finishes.
5. To apply an archive policy to the resources that you are publishing,
❍
❍
For resources published to the My Reports or Public Reports folder, check the Apply Archive Policy option, then specify the
archive policy as required: Archive as New Version or Replace Old Version.
For resources published to the My Components or Public Components folder, specify the maximum number of versions that will
be listed in the version table of the resources.
Note that a folder by itself does not have versions; the archive policy specified for a folder applies to the folder content.
6. If the resources are to be published to the Public Reports or Public Components folder, click the Set Permissions link to specify
user permissions to them according to your requirement.
7. Click OK to start publishing the resources.
Note: The Publish to Local Server option is always available to administrators on the JReport Console page. For end users, the option is
displayed only when they have the privilege of publishing resources and have logged onto JReport Server from a local browser.
Publishing resources from a remote computer
You can publish these types of resources from a remote machine to the server. They are reports, library components, catalogs, and
folders. Only administrators can publish library components. Before publishing remote resources, you must create a zip file or tar file
containing the resources to publish.
To publish resources from a remote computer:
1. Do either of the following to access the Publish to Remote Server dialog:
❍
❍
For administrators, on the JReport Administration page, click Resources on the system toolbar and select Resources from the
drop-down menu. In the Resources panel, browse to the folder where you want to publish the resources, then click Publish to
Remote Server.
For end users, on the JReport Console > Resources page, browse to the folder in which to publish the resources, then on the task
bar of the Resources page, click Publish > To Remote Server.
The Publish to Remote Server dialog is then displayed.
2. Click the Browse button to specify the zipped file which contains the resources you want to publish.
3. Specify where the resources will be published.
❍
❍
If you want to publish the resources directly to the current open folder, check the Publish files and folders in the zipped file
to /XXX checkbox.
If you want to create a new folder in the current open folder to locate the resources,
a. Make sure the Publish files and folders in the zipped file to /XXX checkbox is not selected.
b. In the Resource Node Name box, specify the name of the folder. The name will then be used as the display name of the
folder in the server resource tree.
c. Type a brief description to describe the folder in the Resource Description box.
d. Specify values of the custom fields for the folder if there are custom fields.
e. In the Resource Real Path text field, type a local disk path as the real path of the folder. If you want to enable getting
resources from the real path, check Enable Resources from Real Paths. The local disk resources will be mapped into the
resource node of the folder in the server resource tree and the server will be able to always get resources and updates from
the real path. For details, see Getting and using resources from a real path.
4. If the resources you specify to publish contain reports created in earlier versions, check Automatically Convert Old Report
Schemas, the reports will then be automatically converted into current version JReport reports when publishing finishes.
5. To apply an archive policy to the resources that you are publishing,
❍
❍
For resources published to the My Reports or Public Reports folder, check the Apply Archive Policy option, then specify the
archive policy as required: Archive as New Version or Replace Old Version.
For resources published to the My Components or Public Components folder, specify the maximum number of versions that will
be listed in the version table of the resources.
6. If the resources are to be published to the Public Reports or Public Components folder, click the Set Permissions link to specify
user permissions to them according to your requirement.
7. If you want to use Advanced Publish, click the Advanced Publish button. All resources contained within the zip file will then be
displayed. Check the resources you want to publish and specify the properties for each resource as required.
8. Click OK to start publishing the resources.
Note: When publishing resources from a remote computer, the process is similar to that for a local publish. However, there are
differences:
●
●
Local Publish publishes resources from the machine where the server runs, while a Remote Publish publishes resources from a client
machine using a web browser to the machine where the server runs.
The resource type of Remote Publish can ONLY be a compressed file. You should compress the reports, library components, and
catalog files in advance, and if special fonts are used in the reports or library components, add the corresponding font files into the
compressed file as well. There are two approaches to building a compressed file.
❍
You can compress the resources manually using a third-party tool, such as Winzip and gzip.
❍
You can use jar.exe that the JSDK provides to build a compressed jar file directly. Use the command as follows:
%JAVAHOME%\bin\jar.exe -cvfM %DEST_JAR_FILE% %SOURCE_RESOURCES%
Parameter
Description
%JAVAHOME%
The Java SDK install root.
%DEST_JAR_FILE%
The destination file path and file name. The .jar file will be generated to the path you specify here,
using the file name you provide.
%SOURCE_RESOURCES%
The source file path and file name. Note that specifying a path for this parameter will cause the
generated jar file to contain the same path information. For example, when you extract a jar file
compressed using myReports\*.* for this parameter, the files will be extracted to a folder called
myReports. JReport Server is not able to import a compressed file which contains the path
information, so do not specify a path for this parameter.
To generate a jar file containing no path information, switch to the source folder, and then carry out the compression. For example,
C:\myReports>C:\jdk1.6.0_17\bin\jar -cvfM c:\temp\aa.jar.
The jar file will be generated to c:\temp, as aa.jar, compressing all the files in c:\myReports, and containing no path information.
Always use this method if the folder you are compressing contains reports or library components with Chinese, Korean, or Japanese
names.
Converting reports of earlier versions into current version
If your JReport Server contains reports earlier than V8, during each server runtime lifecycle when you
run such a report for the first time, the JReport Engine has to first convert the earlier version report
into a current version report before running the report. This may result in decreased performance. To
avoid this, JReport Server allows administrators to permanently convert reports earlier than V8 in the
server resource tree to adapt to the current version.
Converting via the Administration UI
The converting UI is available to administrators only. It is used to convert all reports earlier than V8 in
the My Reports folder or Public Reports folder. The converted reports are stored in the same directory.
To convert reports earlier than V8 into current version:
1. On the JReport Administration page, click Resources on the system toolbar, then select
Converting from the drop-down menu.
2. Specify the folders which contain the reports you want to convert.
3. Specify how to save the converted reports.
❍
❍
Replace the Old Repors
Replaces the old reports with the converted reports.
Save as New Report Versions
Saves the converted reports as new report versions in the resource tree.
4. When done, click OK to start converting.
Converting using tool
You can also use rptconv.bat/rptconv.sh located in the <install_root>\bin directory to convert a
report and a type of reports or all reports earlier than V8 in a directory.
Getting and using resources from a real path
Not only can you use the published resources described in section Publishing resources, but also those
resources obtained from a real path. The difference between real path resources and published
resources lies in the way of managing them. Published resources are managed in JReport Server
totally. Real path resources are managed in both the server and the operating system. In the server,
when accessing a resource node which is linked with a real path, the local resources in the real path
are loaded to the node and displayed together with other server resources (including the published
resources) in the node. You cannot delete the real path resources directly from the server UI, but can
only achieve it by removing the resources from the local disk.
To use real path resources, you should specify a real path for a virtual folder. You can then add or
remove resources into or from JReport Server by adding or removing them into or from the real path.
Also, if you do not want to publish resources to the server by using the publish feature, you can set a
real path instead.
The following example uses the resources in the folder /SampleReports obtained from the real path:
1. On the JReport Administration page, click Configuration on the system toolbar, then select
Advanced from the drop-down menu.
2. In the Advanced panel, check the Enable Resources from Real Paths option, save the changes
and then restart the server.
3. Open the Properties dialog of the folder /SampleReports, check Enable Resources from Real
Paths, specify a real path for the demo virtual folder as C:\JReport\Server\reportbak, then
click OK to save the changes.
4. In the Windows directory C:\JReport\Server\reportbak, create three sub directories report1,
report2, and report3, and then copy some reports and catalogs into them.
5. On starting JReport Server, click the virtual folder /SampleReports. You will then see the three
sub folders: report1, report2, and report3 within it, including their reports and catalogs.
Now end users can perform operations on the real path resources, including viewing versions, setting
properties, and report based operations such as running, advanced running, and scheduling.
Notes:
●
You cannot publish resources to a folder that comes from a real path.
●
You cannot use a real path resource as an archive location.
●
●
●
Real path resources themselves can only have one version in the server resource tree, so they do
not support the Archive Policy feature for managing multiple versions.
The relationships of folder real paths do not need to be consistent with that of the resource tree
folders. That is, they are independent of each other. For example, in the resource tree, the folder
ABC, whose real path is C:\FolderABC, has a sub folder DEF. The real path of DEF need not
necessarily be a folder in C:\FolderABC. It can be any folder.
After using the real path resources, under certain special conditions some invalid nodes will be
generated in the server databases. In order to delete the invalid nodes, administrators can perform
the corresponding option on the JReport Administration page to clear unused nodes from the internal
JReport Server database. For details, see Clearing unused nodes from the system database.
Setting default real paths for the Public Reports and Public Components
folders before server starts
JReport Server enables setting the default real paths for the Public Reports and Public Components
folders without having to log onto the server. There are two ways to achieve this goal: setting the real
path during or after installation.
●
Setting during installation
1. When installing JReport Server using the Installation Wizard, select the installation type Custom
Installation for Standalone Server. The Configure System Environment screen is then
available.
2. In the screen, select Advanced from the left panel.
3. Check the Enable Resources from Real Paths option, and then type in the paths separately
in the Public Reports Real Path and Public Components Real Path text fields or specify the paths
using the Browse button.
4. Upon completion of the installation, an install.server.properties file will be created in the
<install_root>\bin directory. When the server starts, it retrieves the file contents, and then
sets the real path for the Public Reports and Public Components folders. Note that the file is
deleted after the server has loaded the file contents.
●
Setting after installation
If you want to set the default real paths for the Public Reports and Public Components folders after
installation, you can create an install.server.properties file in the <install_root>\bin directory
manually. Specify the content in the file as follows:
server.publicReportsRealPath=D:\JReport
server.publicComponentsRealPath=D:\JReport
Customizing TTF font location for resources
The default font path in JReport Server is <install_root>\font. You can set the font path to a
different location by using the following three ways. These are in an order from higher to lower priority:
●
Use the -D parameter to set the system properties key jreport.server.font.path
●
Use the API HttpUtil.initEnv() to set the properties key server.font.path
●
Add a property server.font.path in the server.properties file and set a full path to it.
Notes:
●
The value specified by -D is not stored into the server.properties file.
●
The value specified using API is stored into the server.properties file.
Working with custom fields
Custom fields are user defined fields which can be used as resource properties, the same as Type,
Description, Last Modified, etc.
After a custom field is created and enabled by administrators, it will be available in the resource
information table on both the JReport Administration > Resources panel and the JReport Console >
Resources page. End users can define its value by setting properties.
Creating and enabling custom fields
To create a custom field:
1. On the JReport Administration page, click Configuration on the system toolbar, then select
Custom Field from the drop-down menu.
2. In the Custom Field panel, click New Custom Field on the task bar.
3. In the New Custom Field dialog, provide a name and description for the custom field.
4. To enable the custom field, check the Enabled option.
5. Click OK to create the custom field.
Editing custom fields
To edit a custom field:
1. In the Custom Field panel, select the row where the custom field is in, then click Edit >
Properties on the task bar.
2. In the displayed dialog, modify the name and description for the custom field, and change its
status if required.
3. Click OK to accept the changes.
Deleting custom fields
Administrators can delete the custom fields that are not required at any time. To do this:
1. In the Custom Field panel, select the row where the custom field is. You can select multiple
custom fields.
2. Click Edit > Delete on the task bar.
3. Click OK in the warning message to confirm the deletion.
Setting value to custom fields
When you publish resources to JReport Server, either locally/remotely or from JReport Designer, if
there are custom fields enabled, they will be displayed in the publishing dialog and you can specify the
value of the custom fields for each resource according to your requirements. Also, the custom field
values can be defined by setting resource properties.
Hiding custom fields
By default, all the enabled custom fields will be displayed in the resource information table on both the
JReport Administration > Resources panel and the JReport Console > Resources page. If you want to
hide a custom field from being shown in this table, follow the steps below:
For administrators:
1. Click Profile on the system toolbar of the JReport Administration page, then select Customize
Server Preferences from the drop-down menu.
2. In the General tab, in the Columns Shown in Resources List section, unselect the checkbox in front
of the corresponding custom field.
3. Click OK to accept the setting.
For end users:
End users can hide a custom field on the JReport Console page > Profile > Customize Server
Preferences > General tab as shown in the above method, and besides have a second choice:
1. On the JReport Console > Resources page, click Tools > Preferences on the task bar.
2. In the General tab of the Preferences dialog, unselect the checkbox in front of the corresponding
custom field, then click OK.
Changing resource and folder properties
To change the properties of a resource or folder:
●
For administrators, on the JReport Administration page, click Resources on the system toolbar and
select Resources from the drop-down menu. In the Resources panel, browse to the row that the
resource or folder is in and click the Properties button
in the Control column. In the
corresponding properties dialog, change the settings as required.
●
For end users, on the JReport Console > Resources page, browse to the row that the resource or
folder is in and do either of the following:
❍
Select the row and click Tools > Properties on the task bar of the Resources page.
❍
Select the row, right-click in the row and select Properties from the shortcut menu.
❍
Put the mouse pointer over the row and click the Properties button
on the floating toolbar.
Then, in the corresponding properties dialog, change the settings as required.
See also the following documents for details about the property settings:
●
Catalog Properties dialog
●
Dashboard Properties dialog
●
Folder Properties dialog
●
Library Component Properties dialog
●
Report Properties dialog
●
Result Properties dialog
Assigning permissions
Permissions, associated with resources and folders, are the rules granted to users which control the
operations they can perform on resources and folders.
After you have set permissions for a parent folder, any new resources and sub folders created in that
folder will inherit the same permissions. If you do not want them to inherit these permissions, you can
enable their user permissions and set their permissions separately. Resources and folders will inherit
permissions from their parent folder if their user permissions are not enabled.
To set, view, change, or remove resource/folder permissions:
●
For administrators, in the Properties dialog, click the Set Permissions link, then in the Set
Permissions dialog,
❍
To set up or change permissions for a role, user or group, check Enable Setting Permissions,
select the user, group, or role in the Role Permissions, User Permissions, or Group Permissions
table, and then check or uncheck each permission as required. If the user, group or role is not
listed in the corresponding table, click the Add button to add it and then assign the permissions
accordingly.
❍
To remove resource/folder permissions for all users, groups and roles, uncheck the Enable
Setting Permissions option.
For end users, in the Permissions tab of the Properties dialog,
●
❍
❍
To set up or change permissions for a role, user or group, first check Enable Setting
Permissions, then select the role/user/group in the Selected box and check or uncheck the
required permissions. If the role/user/group is not listed in the Selected box, select the
corresponding radio button below the Available box, add the role/user/group to the Selected box
and then assign the permissions accordingly.
To remove resource/folder permissions for all users, groups and roles, uncheck the Enable
Setting Permissions option.
Notes:
●
●
●
●
●
Security permissions do not apply to the built-in version folders, the My Reports and My Components
folders, and their contents.
To complete a task, you may require more than one permission. For example, to view the properties
of a report, you must have both the Visible and Read permissions.
Some permissions depend on other permissions in order to work, such as Write, Execute, and
Schedule. Allowing anyone of these will also allow the Read permission.
Only members in the administrator role can assign the Grant permission to other users or groups or
roles.
Users that are given the Grant permission can grant permissions to other users in the same group.
Linking resources and catalogs
A resource such as a report or a library component can be linked with a catalog in JReport. The benefits
of a linked catalog compared to a copied catalog are:
●
●
●
There is no need to also copy the wanted catalog to the destination directory when saving the
resource to a different location.
When the resource and its linked catalog are not in the same directory, the resource can still run
with the catalog.
When the linked catalog is updated, the resource using the catalog can run with the updated version.
However, the copied catalog cannot be updated if its original catalog is updated since they are two
independent versions.
When directly running a resource, the linked catalog has higher priority than the catalog specified in
the same folder as the resource (without linked catalog, the resource will run within the selected
catalog in the same folder). As for Advanced Run and Schedule, the default selected catalog is the
linked catalog if there is one, however, you can change it by the provided option Select Another
Catalog.
Setting linked catalog
Linked catalog can be set at server level, folder level, and resource level as follows:
To set linked catalog at server level (this can only be done by administrators):
●
1. Go to the JReport Administration page, click Configuration on the system toolbar and select
Advanced from the drop-down menu.
2. In the Advanced panel, check Enable Linked Catalog, then click the Select Another Catalog
link to specify the catalog which will be used as the linked catalog at server level.
3. Click Save to save the change.
4. Restart JReport Server to make the settings take effect.
●
To set linked catalog at folder/resource level, go to the Properties dialog of the folder/resource,
check Enable Linked Catalog, then specify the linked catalog as required.
❍
❍
Use Specified - If checked, you can specify a linked catalog which can be any catalog in the
server resource tree to the folder/resource.
Use Inherited - If a linked catalog has been specified on the parent level of the folder/resource,
you can use the parent-level linked catalog as the linked catalog of the folder/resource. For the My
Components, Public Components, My Reports, and Public Reports folders, the parent level is the
server level; for the other folders or resources, the parent level is the parent folder.
Notes:
●
●
If a schedule task has been submitted and then the linked catalog in use is modified, the task will
still use the previous catalog until the task information is updated.
When running a page report or web report in Report Studio, you can also save the original catalog as
a linked catalog when saving the report.
●
The saved visual analysis templates are linked to their original catalogs. However, currently visual
analysis templates themselves cannot be customized to link to a different catalog.
Deleting resources
To delete a resource or folder:
For administrators, on the JReport Administration page, browse to the row that the resource or
●
folder is in, then click the Delete button
●
in the Control column.
For end users, on the JReport Console > Resources page, browse to the row that the resource or
folder is in, then do either of the following:
❍
Select the row, right-click in the row and select Delete from the shortcut menu.
❍
Put the mouse pointer over the row and click the Delete button
on the floating toolbar.
Notes:
●
●
The Public Components, My Components, Public Reports and My Reports folders cannot be deleted.
Deleting a resource or folder removes the resource or folder from disk. The deleted resources and
folders cannot be retrieved. Any relevant versions belonging to the resource will also be deleted.
Managing versions
Your resources might change over time. JReport Server uses a versioning system to create and
manage resources that have changed in content and properties owing to updates made to them.
All the resources in the server resource tree: reports, report results, dashboards, library components,
and catalogs, are controlled by versions. A great proportion of resource management tasks are carried
out by managing resource versions.
In addition, JReport Server uses an archive policy to control the resource versions. You can control
whether or not to use multiple versions for a specific resource. Also, you can define the maximum
number of versions that can be listed in the version table. The archive policy can be applied to a single
resource individually, or to many resources in a folder as a whole.
This section shows how to manage resource versions as follows:
●
Creating versions
●
Browsing versions
●
Applying an archive policy
●
Deleting versions
●
Advanced version topics
Creating versions
Generally, report result versions are created when an end user runs a report using Advanced Run or
Schedule Run. However, to create a new version for a report, library component, or catalog, you have
to publish them respectively from outside of JReport Server, and then make the old and the new share
one common resource node. Versions of a dashboard are generated by saving the dashboard, and each
saving action will create a version in the dashboard.
Creating report, library component, or catalog versions
The method for creating a new version to a report, library component, or catalog is by publishing a
resource of the same type with exactly the same name to the same location on JReport Server. For
how to publish, see Publishing resources.
When publishing resources, you need to apply an archive policy so as to make the published resources
saved into the existing resources as a new version.
Note: Catalogs are by default not displayed in the server resource tree on the JReport Console page.
In order to perform operations on catalogs published from outside of JReport Server on the JReport
Console page, you need to enable them to be displayed first by setting the web.page.option.
show_catalog property to true in the server.properties file.
Creating report result versions
A report result version can only be created by advanced running the report or by scheduling the report
to publish it to the versioning system on the JReport Console page.
●
When advanced running a report, in the Archive tab of the Advanced Run dialog:
1. Specify where to save the result version by setting the Archive Location option.
■
■
To generate the report result version in the built-in folder, select Built-in Version Folder.
To generate report result version in a standalone resource node in the resource tree, select
My Reports Folder or Public Reports Folder, and then provide the path and resource name
information in the corresponding box.
2. Apply an archive policy to the version as required and submit the task.
Then, when the report finishes running, a report result version will be generated to the location
specified.
●
When scheduling a report to publish it to the versioning system, in the Publish > To Version tab of
the Schedule dialog:
1. Specify where to save the result version by setting the Archive Location option.
■
■
To generate the report result version in the built-in folder, select Built-in Version Folder.
To generate report result version in a standalone resource node in the resource tree, select
My Reports Folder or Public Reports Folder, and then provide the path and resource name
information in the corresponding box.
2. Apply an archive policy to the version as required and submit the task.
Then, when the schedule task is finished, a report result version will be generated to the location
specified.
Creating dashboard versions
After a dashboard is saved into the server resource tree, you may want to update or modify it, and
then save the changes, which will add a new version in the dashboard.
Notes:
●
●
●
●
The resource path and name refers to the resource path and name in the resource tree. For
instance, /foldername/filename.
For The Public Reports folder option, the first slash mark (/) refers to the Public Reports folder in the
resource tree, and the folder name (foldername) refers to an existing folder in the resource tree.
For The My Reports folder option, the first slash mark (/) refers to the My Reports folder in the
resource tree, and the folder name (foldername) refers to an existing folder in the resource tree.
When generating report result versions in an existing standalone resource node in the resource tree,
for example, creating a new version for a resource node, you should make sure to provide the path
and name of the existing resource for The Public Reports folder or The My Reports folder option.
Browsing versions
To view the version information of a resource:
●
For administrators, on the JReport Administration page, click Resources on the system toolbar and
select Resources from the drop-down menu. In the Resources panel, browse to the resource, then
click the Version button
●
in the Control column.
For end users, on the JReport Console > Resources page, browse to the resource, then do either of
the following:
❍
Select the resource row and click Tools > Version on the task bar of the Resources page.
❍
Select the resource row, right-click in the row and select Version from the shortcut menu.
❍
Put the mouse pointer over the resource row and click the Version command button
floating toolbar.
on the
The versions that a resource hosts are organized in the version table.
Version table
Relevant information about the versions that a resource hosts, such as the version date, version
number, is collected and represented in a table, called the version table.
The version table is composed of the following columns:
●
●
●
●
Catalog Versions Table
Column
Description
Version Date
The date and time of when the version was generated.
Version Number
The serial ID that identifies a version in the version table.
Report Versions Table
Column
Description
Version Date
The date and time of when the version was generated.
NLS Editor
Administrators can edit NLS for a specified report version by clicking the
corresponding link.
Version Number
The serial ID that identifies a version in the version table.
Report Result Versions Table
Column
Description
Result
The output file formats. You can click the links to view the output files.
Version Date
The date and time of when the version was generated.
Parameter File
The parameter file name. You can click the underlined file name to view the
parameters.
Creator
The ID of the user who created the version.
Version Number
The serial ID that identifies a version in the version table.
Dashboard Versions Table
●
Column
Description
Version Date
The date and time of when the version was generated.
Version Number
The serial ID that identifies a version in the version table.
Library Component Versions Table
Column
Description
Version Date
The date and time of when the version was generated.
NLS Editor
Administrators can edit NLS for a specific library component version by clicking
the corresponding link.
Version Number
The serial ID that identifies a version in the version table.
Tip: Some columns in the tables are not shown by default. To have them displayed, locate the table,
click Preferences on the task bar if available, check the corresponding items in the Preferences dialog,
then click OK to save the settings.
Applying an archive policy
JReport Server uses an archive policy to control resource versions. The archive policy can be applied to
a single resource individually or to many resources in a folder as a whole. It can also be applied when
you publish resources to the server resource tree or when you advanced run or schedule a report.
When applying an archive policy, you can choose whether to use multiple versions for a resource or
always use the new version to replace the old one.
Archive as New Version
Specifies to use multiple versions for the specified resource.
●
Maximum Number of Versions
Specifies the maximum number of versions that will be listed in the version table of the resource. The
default value is 0, which means that the version number is unlimited.
Replace Old Version
Specifies to replace the old version when a new version is generated.
If there is no archive policy specified for a resource, the resource will inherit the archive policy from its
parent object. If afterwards you then specify an archive policy for the resource, the new policy will
override the one inherited from the parent object.
Applying an archive policy to resources in the resource tree
To apply an archive policy to a resource in the resource tree, refer to the table below:
If you
want to
Apply
archive
policy when
publishing
resource
Then do
Result
In the publish resource dialog (for how to access the dialog,
see Publishing resources):
The archive policy is
applied to the resource.
●
●
Apply
archive
policy to a
folder
Note: A folder by itself
does not have versions;
the archive policy
specified for a folder
If the resource is to be published to the My Components
applies to the folder
or Public Components folder, set the Maximum Number of content.
Versions option as required.
If the resource is to be published to the My Reports or
Public Reports folder, set the Apply Archive Policy option
as required.
1. Access the Properties dialog for the folder (for how to
access the dialog, see Changing resource and folder
properties).
2. In the dialog,
❍
❍
For folder in the My Reports or Public Reports folder
(including the root folder itself), set the Apply
Archive Policy option as required, then click OK.
For folder in the My Components or Public
Components folder (including the root folder itself),
set the Maximum Number of Versions option as
required, then click OK.
The archive policy will be
applied to all of the
folder content.
Note: This does not
include resources that
already have individually
applied archive policies.
Apply
archive
policy to a
resource
1. Access the Properties dialog for the resource (for how to
access the dialog, see Changing resource and folder
properties).
2. In the dialog,
❍
❍
Apply
archive
policy when
running a
task in
Advanced
mode
Apply
archive
policy when
scheduling
a task
For resource in the My Reports or Public Reports
folder, set the Apply Archive Policy option as
required, then click OK.
For resource in the My Components or Public
Components folder, set the Maximum Number of
Versions option as required, then click OK.
1. On the JReport Console > Resources page, browse to
the resource you want to run.
2. Put the mouse pointer over the resource row and click
The archive policy is
applied to the resource,
overriding its inherited
archive policy.
Note: If you leave the
archive policy
unspecified, the resource
will inherit the archive
policy from its parent
object, for example, the
folder it resides in.
The archive policy will be
applied to a result type
resource.
Note: If you leave the
Apply Archive Policy
the Advanced Run button
on the floating toolbar. option unchecked, the
3. In the Archive tab, check the Auto Archive Properties resource will use its old
archive policy or inherit
option.
the archive policy from
its parent object, for
4. Finish the other relevant information, making sure that
example, the folder it
Archive Location is set to the resource tree folder.
resides in.
5. Set the Apply Archive Policy option as required, and
then click Finish.
1. On the JReport Console > Resources page, browse to
the resource you want to schedule.
2. Put the mouse pointer over the resource row and click
the Schedule button
on the floating toolbar.
3. In the Publish tab, click the To Version sub tab, then
check the Publish to Versioning System option.
4. Finish the other relevant information, making sure that
Archive Location is set to the resource tree folder.
5. Set the Apply Archive Policy option as required, then
click Finish.
The archive policy is
applied to a result type
resource.
Note: If you leave the
Apply Archive Policy
option unchecked, the
resource will use its old
archive policy or inherit
the archive policy from
its parent object, for
example, the folder it
resides in.
Applying an archive policy to the built-in version table
The above table applies to the resource in the resource tree only. The versions in the built-in version
folder are controlled by its own archive policy.
To apply an archive policy to the built-in version table, refer to the table below:
If you
want to
Apply
archive
policy to a
built-in
version table
Then do
1. Access the version table for the resource (report type) (for how to access the table,
see Browsing versions).
2. In the Report Result Versions tab, check the Maximum Number of Versions
option, specify the versions to be saved as required, then click OK.
Apply
archive
policy when
running a
task in
Advanced
mode
1. On the JReport Console > Resources page, browse to the resource you want to run.
2. Put the mouse pointer over the resource row and click the Advanced Run button
on the floating toolbar.
3. In the Archive tab, check the Auto Archive Properties option.
4. Finish the other relevant information, making sure that Archive Location is set to
the Built-in Version Folder.
5. Set the Apply Archive Policy option as required, then click Finish.
Apply
archive
policy when
scheduling
a task
1. On the JReport Console > Resources page, browse to the resource you want to
schedule.
2. Put the mouse pointer over the resource row and click the Schedule button
on the floating toolbar.
3. In the Publish tab, click the To Version sub tab, then check the Publish to
Versioning System option.
4. Finish the other relevant information, making sure that Archive Location is set to
Built-in Version Folder.
5. Set the Apply Archive Policy option as required, then click Finish.
Deleting versions
After creating versions, periodically you may want to delete some expired or unused versions. You can
choose to remove these versions manually or configure JReport Server to delete them automatically.
When removing the versions using the user interface, the archive versions stored on disk are also
physically deleted.
Deleting manually
To delete some versions of a resource manually, first open the version table of the resource (for how to
access the table, see Browsing versions), then:
●
For administrators, in the version table, check the checkbox ahead of the versions that you want to
remove and then click the Delete link.
For end users, in the version table, find the version you want to remove, then:
●
❍
Select the version row and click Edit > Delete on the task bar.
❍
Select the version row, right-click in the row and click Delete on the shortcut menu.
❍
Put the mouse pointer over the version row and click the Delete button
.
After receiving "The version has been deleted" message, view the version information again. You will
find that the version you selected has now been removed from the version table.
Deleting automatically
There are two approaches to automatically deleting versions:
●
Apply Archive Policy
The Apply Archive Policy controls the number of versions that will be recorded in the version table of
a resource.
When creating a resource version, you can specify the maximum number that will be saved. If the
number of versions exceeds the specified number, the oldest version will automatically be removed
from the version list.
For example, if you specify Maximum Number of Versions as 5, when the sixth version is created, the
first version will automatically be removed.
●
Result Auto-delete
Result Auto-delete controls the duration of versions. It is only applicable to report result versions.
When creating a report result version, you can specify a certain period of time to keep the version.
The version will automatically be removed from the version list after the number of days or the
specified date.
For example, if you specify "Result Expires in 30 days", it will be automatically removed 30 days after
its creation.
Advanced version topics
The following sections cover advanced version topics for administrators and developers. It will give you
an understanding of version structure in depth.
●
Version resource structure in the server database
●
Storage of versions on disk
●
Topics for developers
Version resource structure in the server database
Information about versions, folders, nodes, the security system, the completed table, and server
runtime performance are all stored in the default database Derby. Also, since JReport Server provides
multiple database support, you can configure your own database to store server data. For production
systems it is recommended to use the same DBMS as your database application so the server data will
be backed up with the rest of the application.
This section discusses how view resources were stored in the server database - Derby.
To open the Derby database, use Apache toolkit ij. ij is Derby's interactive JDBC scripting tool. It is a
simple utility for running scripts or interactive queries against a Derby database. ij is a Java application
that you start from a command window such as an MS-DOS Command Window or the Unix shell. ij
provides several non-SQL commands for ease in accessing a variety of JDBC features for testing.
To open the defaultRealm.* files:
1. Start ij.bat in <server_install_root>\derby\bin.
2. Connect to database. To connect to a Derby database, you need to perform a valid database
connection URL. ij automatically loads the appropriate driver based on the syntax of the URL. The
following example shows how to connect defaultRealm by using the Connect command and the
client driver:
D:>java org.apache.derby.tools.ij
ij version 10.5
ij> connect 'jdbc:derby://localhost:8886/defaultRealm';
ij>
3. After connected to the database successfully, ij allows the execution of Derby SQL statements
interactively or via scripts.
Note: All statements must be terminated with a semicolon.
Example 1: Finding result version information from the database
Execute the command SELECT * FROM RESULTVERSION_2 WHERE CREATOR='admin'; to
retrieve result versions which were created by the user 'admin'.
Example 2: Finding catalog version information from the database
Execute the command SELECT * FROM CATALOGVERSION_3; to fetch all catalog versions.
4. For more information about Derby and ij, please visit Apache website http://db.apache.org/
derby/.
Note: Don't delete, update or insert data into the database. It is recommended that all modifications to
the database be done from JReport Server instead of in the ij. Otherwise, it may result in JReport
Server crashing if invalid data is found.
Storage of versions on disk
A working directory <reporthome>\history has been defined for use by the system database. Rather
than store all the actual resources in the DBMS, the DBMS stores only pointers to the actual files.
JReport Server uses this folder to store all of the parameter information and version files. By default,
JReport Server creates 100 folders in its history folder (<reporthome>\history), and each of these
folders can contain a further 3000 subfolders. These subfolders however cannot hold any further
subfolders.
First, JReport Server puts the history information, such as archive versions and parameter files in folder
1. When the amount of subfolders in folder 1 reaches the maximum subfolder amount, it starts to put
files in folder 2. When folder 2 is filled up, folder 3 will be used, then folder 4, folder 5, and so on, until
all 100 folders have been filled up.
When all the 100 folders have been filled up with subfolders, JReport Server will then create another
100 folders, named 101 to 200, and will continue to store the history information in these folders,
starting from folder 101. When the second 100 folders are full, another 100 folders will be created, and
so on.
Changing the storage folder
JReport Server provides a server.properties file for you to configure the server. If you want to specify a
folder other than <reporthome>\history to store the version files, you can set the folder for the
resource.share.hist.dir property in this file.
The following describes the process of changing the storage folder:
1. After installing and starting JReport Server, the server.properties file is generated in the
<install_root>\bin folder. You can then set the folder that your server data is to be stored in, in
the resource.share.hist.dir property as resource.share.hist.dir=D:\ServerData.
2. Delete the properties, profiling and history sub folders from the <install_root> folder.
3. Restart JReport Server. The demo resources in the <reporthome>\jreports directory will now be
stored in the specified ServerData folder.
4. After the above procedures have been performed, all parameter information and version files
created will be stored in the specified ServerData folder.
Topics for developers
Other than implementation from the JReport Server UI, advanced users are also allowed to manage versions
using the JReport Server API and RMI API.
The JReport Server API and RMI API is a set of Java programming interfaces that run reports, explore report
resources, and provide access control for report servers. It is mainly used for writing servlets, JSPs and Java
applications with report server features. You can find documentation that describes the usage of the JReport
Server API in the section JReport Server APIs and Remote APIs.
Program examples to show how to publish a report to the versioning system, how to run a report, and how
to publish a catalog/report can be found in the <install_root>\help\samples\APIServer folder.
Applying an archive policy
You may find that whenever you create catalog/report template versions, or report result versions, an
archive policy is applied. The archive policy is a series of settings for controlling whether or not to use
multiple versions for a specific resource, for specifying the maximum version amount and archive location,
and for controlling whether or not to auto-delete versions after a certain period of time.
Archive policy parameters
Parameters
Values
Description
APIConst.
TAG_ENABLE_ARCHIVE_POLICY
true
Whether or
not to apply a
new archive
policy.
APIConst.TAG_AUTO_ARCHIVE
true
/false
/false
APIConst.
TAG_ARCHIVE_LOCATION
Parameters
Description
Whether or
not to autoarchive the
viewed result.
0
Built-in
version folder
is used as the
result
archiving
location.
1
The My
Reports folder
is used as the
result
archiving
location.
APICONST.
TAG_ARCHIVE_MY_DESTINATION
2
Values
The Public
Reports folder
is used as the
result
archiving
location.
Sub folder name in
the My Reports
folder for this user.
For example, /
rtp100, which
means to output the
file to /
USERFOLDERPATH/
<userid>/rtp100.
APICONST.
TAG_ARCHIVE_PUBLIC_DESTINATION
APIConst.
TAG_REPLACE_OLD_VERSION
true
APIConst.
TAG_ARCHIVE_NEW_VERSION
true
APICONST.
TAG_NEED_MAXVERSION
0 or N
The number
of versions to
keep for this
resource
result.
APICONST.TAG_NEED_EXPIRE
true
Whether or
not to auto
delete this
version.
/false
/false
/false
APIConst.TAG_EXPIRE_METHOD
0
1
Sub folder name in
the Public Reports
folder for all the
users. For
example, /
ActimizeTest/rtp100
Whether or
not to replace
the previous
version.
Whether or
not to archive
the next
version as a
new version.
Version
expires after
a number of
days.
APIConst.DAY_EXPIRE
Number
The number of days
until a version
expires.
APIConst.TAG_EXPIRE_YEAR
Number
The year of
expiration.
APIConst.TAG_EXPIRE_MONTH
Number
The month of
expiration.
APIConst.TAG_EXPIRE_DATE
Number
The date of
expiration.
Version
expires after
a certain
date.
Scheduling report results to the versioning system
You can use the Java class HttpRptServer with the following methods to schedule report results to the
versioning system: runTask(), and submitScheduledTask().
There is a Hashtable argument for these two methods, which includes the parameters used for running
tasks. Here are some parameters that you will need when specifying your Hashtable for scheduling to
version:
Parameters
Values
Description
APICONST.
TAG_TO_VERSION
true
Whether or not
to schedule to
the versioning
system.
/false
Parameters
Values
Description
APICONST.
TAG_TO_VERSION_EXCEL
true
Whether or not
to schedule to
an Excel
version.
/false
APICONST.
TAG_TO_VERSION_HTML
true
APICONST.
TAG_TO_VERSION_PDF
true
APICONST.
TAG_TO_VERSION_PS
true
APICONST.
TAG_TO_VERSION_RSD
true
APICONST.
TAG_TO_VERSION_RST
true
APICONST.
TAG_TO_VERSION_RTF
true
APICONST.
TAG_TO_VERSION_TXT
true
APICONST.
TAG_TO_VERSION_XML
true
/false
/false
/false
/false
/false
/false
/false
/false
Whether or not
to schedule to
an HTML
version.
Whether or not
to schedule to
a PDF version.
Whether or not
to schedule to
a PostScript
version.
Whether or not
to schedule to
a Page Report
Result version.
Whether or not
to schedule to
an rst version.
Whether or not
to schedule to
an rtf version.
Whether or not
to schedule to
a TEXT
version.
Whether or not
to schedule to
an XML
version.
Obtaining version information
You will be able to fetch version records with the following function calls:
1. Get the resource manager from the HttpRptServer:
public ResourceManager getResourceManager()
2. Then use the following methods to obtain a version:
❍
❍
❍
❍
❍
❍
Report version
getReportVersions(String userID, String rptName)
Report Result version
getResultVersion(String userID, String rptName, int versionNumber)
Catalog version
getCatalogVersions(String userID, String catName)
Result version
getResultDocVersions(String userID, String resultDocName)
Dashboard version
getReportVersions(String userID, String dashboardName)
Library component version
getLCVersions(String userID, String lcName)
Note: userID is only used for checking privilege in this method, and not for filtering the submitter.
Managing security
JReport Server provides a security system which allows you to set up and maintain security on the
server and protect your resources from inappropriate access by users.
This section focuses on accomplishing security management in JReport Server by means of setting up
roles, users, and assigning certain permissions.
You can find other information related to server security in the sections Security and Server security
system.
This section covers the following topics:
●
Managing realms
●
Managing user accounts
●
Managing groups
●
Managing roles
●
Managing privileges
●
Managing aliases
●
Managing organizations
Managing realms
To manage realms, you must be a member of the administrator role in order to access the JReport Administration page.
Then, on the JReport Administration page, click Security on the system toolbar and go to the Realm panel, where you
can manage the realms as required.
The following topics detail how to manage a realm:
Creating a new realm
1. Click the Create a New Realm link.
2. In the New Realm dialog, type a name for the realm, and select an authentication mode as the scheme.
Basic Authentication uses the base64 encryption method as defined by RFC 1945. Digest Authentication uses the
MD5 encryption method as defined by RFC 2069. Basic Authentication is lower security but is usually what is used on
intranets. Digest Authentication provides much higher security and is usually used with SSL in a highly secure
environment.
3. When done, click OK, and the realm will then be added to the realm list table.
When a new realm is created, it is assigned with built-in users, groups, and the default resource tree. Remember to
activate the correct realm before allowing clients to visit.
Activating a realm
The realm must be activated before its content, such as resources, users, groups, and roles, and it can then be accessed
by the client users. There can be only one active realm at any time.
To activate a realm:
1. On the JReport Administration page, click Configuration on the system toolbar, and then click Service from the
drop-down menu.
2. Select the realm you want to activate from the Active Realm drop-down list.
3. Click Save to apply the settings.
4. Restart JReport Server so that the changes can take effect.
Managing the users, groups and roles in an inactive realm
Users, groups and roles are only available when the realm they belong to is active. However, users, groups and roles in
an inactive realm can still be managed by users in the administrator role.
To manage users, groups and roles in an inactive realm:
1. Click the Select link in the Control column of the realm list table to select the realm you want to manage.
All realms in JReport Server are listed in the realm list table. The State column shows the status of the realms. An
active realm is marked as Active Realm. A selected realm is marked as Selected Realm. If the realm is both active
and selected, it is marked as Active Realm.
2. Click Security and then User, Group or Role to manage the selected realm.
Information about users, groups and roles in the selected realm is listed in the User, Group, and Role panels.
Deleting a realm
If you find a realm is no longer required, you can delete it by clicking the corresponding Delete link in the Control column
of the realm list table.
Managing user accounts
To manage user accounts, you must be a member of the administrator role in order to access the JReport Administration page.
Then, on the JReport Administration page, click Security on the system toolbar and go to the User panel, where you can manage
the user accounts as required.
The following topics describe how to manage a user account.
Creating a new user account
1. In the Security > Realm panel, select a realm to which you want to add the user.
2. In the Security > User panel, click the Create a New User link.
3. In the New User dialog, provide the information for the user as required.
4. Click OK, and the user will then be added to the user account table.
Modifying a user account
1. In the Security > Realm panel, select the realm in which the user is.
2. In the Security > User panel, click the name of the user.
3. In the Edit User dialog, edit the user information as required.
4. When done, click OK to accept the changes.
Adding roles to a user
A user can be assigned more than one role. A user that holds multiple roles has all the privileges that these roles have.
To add roles to a user:
1. In the Security > Realm panel, select the realm in which the user is.
2. In the Security > User panel, click the role(s) link of the user.
3. In the displayed page, click the Add Roles link.
4. In the role table, check the roles that you want to add to the user, then click the Add button.
5. Click Security > User to return to the user list.
Adding a user to groups
A user can be assigned to more than one group. A user that belongs to multiple groups has all the privileges that these groups
have.
To add a user to some groups:
1. In the Security > Realm panel, select the realm in which the user is.
2. In the Security > User panel, click the group(s) link of the user.
3. In the displayed page, click the Add Groups link.
4. In the group table, check the groups that you want to add the user to, then click the Add button.
5. Click Security > User to return to the user list.
Removing roles/groups from a user
If you want to remove certain roles a user holds, or some groups a user belongs to from a user, follow the steps below:
1. In the Security > Realm panel, select the realm in which the user is.
2. In the Security > User panel, click the role(s)/group(s) link of the user.
3. In the roles/groups table of the user, check the roles/groups you want to remove, then click the Remove button.
Once a role or group is removed from a user, the user will no longer have the privileges the role or group has.
Auditing a specific user
You can have the server to audit a user, and the resulting information will be written into the log files.
To audit a user:
1. In the Security > Realm panel, select the realm in which the user is.
2. In the Security > User panel, click the Auditing link of the user.
3. In the Auditing dialog, specify the events which you want to have audited for this user.
4. When done, click OK to accept the changes.
Changing the password of a user
1. In the Security > Realm panel, select the realm in which the user is.
2. In the Security > User panel, click the Change Password link of the user.
3. In the Change Password dialog, specify the password of the current logged in user.
4. Specify the new password for the user and confirm it by entering it a second time.
5. When done, click OK to accept the changes.
Setting user preferences
1. In the Security > Realm panel, select the realm in which the user is.
2. In the Security > User panel, click the Preferences link of the user.
3. In the Preferences dialog, specifies the server preferences and Page Report Studio preferences for the user accordingly.
4. When done, click OK to accept the changes.
Deleting a user account
If you find a user account is no longer required, you can delete it by clicking the corresponding Delete link in the Control column of
the user account table. However, the built-in user accounts, such as admin and guest, and users that hold roles other than the
everyone role, or that belong to any group, cannot be deleted. A user cannot delete himself from the user list either.
Managing groups
To manage groups, you must be a member of the administrator role in order to access the JReport Administration page.
Then, on the JReport Administration page, click Security on the system toolbar and go to the Group panel, where you
can manage the groups as required.
The following topics explain how to manage a group.
Creating a new group
1. In the Security > Realm panel, select a realm to which you want to add the group.
2. In the Security > Group panel, click the Create a New Group link.
3. In the New Group dialog, specify the settings for the new group.
4. When done, click OK, and the new group will then be added into the group list table.
5. Click Security > Group to return to the group list table.
Modifying a group
1. In the Security > Realm panel, select the realm in which the group is.
2. In the Security > Group panel, click the name of the group.
3. In the Edit Group dialog, edit the group information as required.
4. When done, click OK to accept the changes.
Editing members of a group
You can edit members of a group, such as adding a new member, or removing a member from the group.
To edit the members in a group:
1. In the Security > Realm panel, select the realm in which the group is.
2. In the Security > Group panel, browse to the specific group, and then click the member(s) link.
3. Edit the members of the group as follows:
❍
❍
To remove a member from the group, check the member and then click the Remove button.
To add a member to the group, click the Add Members link, check the new member, and then click the Add
button.
Notes:
●
A group can have more than one child member and parent member.
●
A parent member cannot be added to the current group as its child member.
Deleting a group
If you find a group is no longer required, you can delete it by clicking the corresponding Delete link in the Control column
of the group list table. However, groups that are not empty, having child members or parent members, cannot be deleted.
Managing roles
To manage roles, you must be a member of the administrator role in order to access the JReport Administration page. Then,
on the JReport Administration page, click Security on the system toolbar and go to the Role panel, where you can manage
the roles as required.
The following topics describe how to manage a role.
Creating a new role
1. In the Security > Realm panel, select a realm to which you want to create the role.
2. In the Security > Role panel, click the Create a New Role link.
3. In the New Role dialog, specify the settings for the role.
4. Click OK, and the new role will then be added to the role list table.
Modifying a role
1. In the Security > Realm panel, select the realm in which the role is.
2. In the Security > Role panel, click the name of the role.
3. In the Edit Role dialog, edit the role information as required.
4. When done, click OK to accept the changes.
Editing members of a role
You can edit the members of a role, such as adding a new user or role, or removing a member from the role.
To edit the members in a role:
1. In the Security > Realm panel, select the realm in which the role is.
2. In the Security > Role panel, browse to the specific role, and then click the member(s) link.
3. Edit the members of the role as follows:
❍
To remove a member from the role, check the member and then click the Remove button.
❍
To add a member to the role, click the Add Members link, check the new member, and then click the Add button.
Notes:
●
A role can have more than one child group, child role and parent role.
●
●
A parent role cannot be added to the current role as its child.
Some members cannot be removed from the role they belong to, such as admin in the administrator role and guest in the
everyone role. A user cannot remove himself from the administrators role.
Deleting a role
If you find a role is no longer required, you can delete it by clicking the corresponding Delete link in the Control column of the
role list table. However, the built-in roles, such as administrators and everyone, and roles that are not empty, cannot be
deleted.
Managing privileges
JReport Server offers these types of privileges for users, groups, and roles: Publish, Advanced Properties, and Message Table
Manipulation. Users that are granted the Publish privilege will be able to publish resources to JReport Server, while users that
have the privilege of Advanced Properties are allowed to view advanced information of version properties such as catalog
connections and report related resources.
To manage privileges, you must be a member of the administrator role in order to access the JReport Administration page. Then,
1. On the JReport Administration page, click Security on the system toolbar and select Realm from the drop-down menu.
2. Select the realm in which the role/group/user is. Then click Security on the system toolbar and select Privilege from the
drop-down menu.
You can then grant and remove role/group/user privileges in the panel.
Granting role/group/user privileges in the Privilege panel
●
●
For roles/groups/users that already have privileges
Roles/groups/users that already have privileges are listed in the Role Privileges/Group Privileges/User Privileges table. To
assign privileges to them, you just need to check the checkbox below the type of privilege you want to grant. Then click Save
to apply the changes.
For roles/groups/users that have had neither of the privileges
1. In the Privilege panel, click the Add button. The Privilege dialog will then appear.
2. To assign privileges to a role/group/user, select the Role Privileges/Group Privileges/User Privileges tab accordingly.
3. Choose the specific role/group/user from the list by selecting the checkbox before its name.
4. Check the checkbox below the type of privilege you want to grant.
5. Click the OK button to apply the changes. The role/group/user that has been granted new privileges will be added into
the Role Privileges/Group Privileges/User Privileges table.
Removing privileges from a role/group/user in the Privilege panel
To remove privileges from a role/group/user, you can choose either of the following two methods:
●
●
To remove a privilege from a role/group/user, uncheck the checkbox below the privilege, and then click Save to apply the
changes.
To remove all privileges from a role/group/user, first select the role/group/user, and then click the Remove button. By doing
this, the role/group/user will be deleted from the Role Privileges/Group Privileges/User Privileges table.
Granting and removing role/group/user privileges in the Role/Group/User panel
1. In the Security > Realm panel, select the realm in which the role/group/user is.
2. In the Security > Role/Group/User panel, click the underlined role/group/user name.
3. In the Edit Role/Edit Group/Edit User dialog, check or uncheck the target privileges.
4. Click the OK button to apply the changes.
Managing aliases
JReport Server organizes its files and directories into a Resource Tree. Aliases are used to provide certain "views" of the tree, and
allow different users to have different views. For example, you can set an alias resource tree (based on the resource tree) for
Mary in Sales, which enables her to only see the Sales resource node, allowing her direct access to the report files she is
interested in. An alias is a combination of users and the resource node.
However, in order to manage aliases, you must be a member of the administrator role in order to access the JReport
Administration page.
Setting an alias resource tree for a role, group, or user
1. Log onto the JReport Administration page.
2. Click Security on the system toolbar and select Realm from the drop-down menu.
3. Select the realm in which the role, group, or user is.
4. Click Security on the system toolbar and select Alias from the drop-down menu.
5. Set an alias resource tree for a role/group/user, click the corresponding set alias link.
6. Select a role/group/user, and then click the Next button to open the Set Alias dialog.
7. Click the New button to create a new alias node in the root node.
8. In the Alias Name field, replace the default name newAlias with a name for the alias.
9. Click the Browse button to specify a destination resource from the server resource tree that is to be associated with the
new alias node. If you do not want the alias node to be shown in the alias resource tree, check the Hide This Alias option.
10. Click the OK button to complete the creation of the new alias node.
11. Use the following steps to create further alias nodes:
a. Select the node in which you want to create a new alias node.
b. Click New to create.
c. In the Alias Name field, replace the default name newAlias with a name for the alias.
d. Click the Browse button to specify a destination resource from the server resource tree that is to be associated with
the new alias node.
e. If you do not want the alias node to be shown in the alias resource tree, check Hide This Alias.
f. Click the OK button to complete the creation of the new alias node.
12. After you have finished with the alias resource tree, click the Close button to exit the dialog.
You will now see that the just set role/group/user is listed in the corresponding alias list in the Alias panel.
Viewing the alias resource tree of a role, group, or user
1. In the Security > Realm panel, select the realm in which the role, group, or user is.
2. In the alias list of the Security > Alias panel, select the underlined name of the role/group/user you want to view.
3. The Set Alias dialog will then be opened for you to view the alias resource tree information of the role/group/user.
Editing the alias resource tree of a role, group, or user
1. In the Security > Realm panel, select the realm in which the role, group, or user is.
2. In the alias list of the Security > Alias panel, select the underlined name of the role/group/user you want to edit.
3. The Set Alias dialog will then be displayed for you to edit the alias resource tree of the role/group/user. You can edit by
hiding/unhiding an alias node, creating a new alias node, or removing an existing alias node.
❍
To hide/unhide an alias node:
a. Select the alias node in the alias resource tree.
b. Check/uncheck the Hide This Alias option, and then click OK.
❍
To create a new alias node:
a. Select the alias node in which you want to create a new alias node.
b. Click New.
c. In the Alias Name field, replace the default name with a name.
d. Click the Browse button to search for the destination resource from the Server resource tree that is to be associated
with the alias node.
e. Click OK to create the alias node.
❍
To remove an existing alias node:
a. Select the alias node from the alias resource tree.
b. Click Remove to remove the alias node.
Notes:
●
An alias tree is based on the resource nodes (not virtual resource nodes) of the resource tree.
●
By default, the alias resource tree root for each user refers to the resource tree root.
●
When an alias tree is activated for a user, all resource access is then controlled by the alias resource tree.
Managing organizations
JReport Server administrator can organize users into different groups with the organization feature. An
organization is a group of users that has its own administrator. The organization administrator can
define which users can use which dynamic connections within the organization.
There are two types of admin in the server security system:
●
●
Root admin
The administrator who has the administrators role. It must be a non-organization user. Root admin
can manage all the dynamic connections.
Organization admin
The administrator who has the administrators role in an organization. Organization admin can
manage dynamic connections for users/groups/roles in the organization.
There are two types of normal users in the server security system:
●
●
Non-organization users
Belong to no organizations.
Organization users
Belong to specific organizations.
Organization is a separately licensed feature of JReport Server. It is installed together with JReport
Server so only the license key needs to be updated to enable it to work. To find out how to license
Organization please contact Jinfonet sales at [email protected] or contact your Enterprise Account
Manager.
When organization is enabled, you need to specify the organization name before logging in JReport
Server. The available organizations are listed in the drop-down list for selection. The organization item
System means that the login user is a non-organization user. For organization users, the correct
organization name must be provided, otherwise they cannot log in.
When organization is disabled, only non-organization users can log in.
Organization definition
Within each organization, there is a built-in admin and two built-in roles:
Built-in admin
●
❍
The full name of the default admin is organization administrator, also as organization admin.
❍
The default admin's user name is admin.
❍
❍
●
The default admin password is admin, which could be changed by the organization admin itself. If
the password is forgotten, the JReport root admin can retrieve it since the root admin can reset
password for all users.
The default admin owns the administrators role and everyone role by default, and it must always
have the administrators role.
Two built-in roles
❍
❍
administrators
It has no parent role by default. It enables Publish and Advanced Properties privileges by default.
everyone
It has no parent role by default. It disables Publish and Advanced Properties privileges by default.
Organization name cannot be System since the name has been used for the category name to
represent non-organization users.
Organization users and non-organization users
Users, groups, and roles created in an organization are called organization users/groups/roles. And
users, groups, and roles that do not belong to any organization are called non-organization users/
groups/roles. When upgrading from a version earlier than version 13, the users, groups, and roles in
the earlier version are all regarded as non-organization principals.
An organization user/group/role can belong to any other non-organization group/role, but a nonorganization user/group/role cannot belong to any organization group/role. An organization user/group/
role cannot belong to any group/role of other organizations.
Organization admin cannot add users/groups/roles to non-organization groups/roles. Only root admin
can do that.
The naming rule of an organization user is composed of the organization name and the user name
separated by \. The format is [Organization Name]\[User Name]. For example, a\b, here a is the
organization name and b is the user name.
If organization is disabled, the organization users/groups/roles will not be supported. However the
information will be saved in the server and can be retrieved next time when organization is enabled
again.
Relationship with dynamic connections
The dynamic connections are categorized at the organization level. If the root admin creates a dynamic
connection, the connection maps to no organization. If an organization admin creates a dynamic
connection, the connection maps to the organization.
If a dynamic connection is defined in an organization, all users/groups/roles must be from the same
organization. If a connection is defined in non-organization, all users/groups/roles must be from nonorganizations.
Root admin can define, view and edit all the dynamic connections.
Creating organizations
The root admin can create and delete organizations.
To create an organization:
1. On the JReport Administration page, click Configuration on the system toolbar and then select
Organizations from the drop-down menu.
2. In the Organizations panel, click the Create link. The Create Organization dialog is displayed.
3. Specify the name of the organization, the maximum number of users allowed in the organization,
and the description about the organization, then click OK.
The organization will be created and listed in the Organizations panel.
See also Create Organization dialog for details about the options in the dialog.
In the Organizations panel, the root admin can further edit the maximum number of users in the
organizations, or delete the organizations that are not required.
●
●
To edit the maximum number of users in an organization, double-click its number in the Max
Number of Users column to enter the edit mode. Select a value from the drop-down list or input an
integer number in the combo box directly, then click outside of the combo box to accept the change.
The x in the combo box is used to clear the input text.
To delete an organization, select the checkbox ahead of the organization and then click Delete. To
delete all the organizations at a time, select the checkbox on the column header and then click
Delete.
JReport Administration page for organization admin
After the root admin create an organization, the organization admin of the organization will be able to
log in JReport Server by the default user name admin and the default password admin.
On the JReport Administration page, the organization admin is able to define users, groups, roles, and
dynamic connections for the users within the organization.
The JReport Administration page contains two tabs on the system toolbar for organization admin:
●
●
Configuration
The Configuration tab displays the Dynamic Connections panel directly. The organization admin can
define dynamic connection for the users in the organization.
Security
The security tab contains four items: User, Group, Role, and Privilege. For each item the UI is the
same as that on the normal JReport Administration page. The differences are that organization admin
can only see the users/groups/roles in the organization and cannot change the realm.
Connecting to JReport Server from JReport Designer
In JReport Designer, when publishing resources to JReport Server or synchronizing server users for
CLS/RLS/MLS, you need to connect to the server firstly. In the Connect to JReport Server dialog, User
Name should include the organization name when organization is enabled and when the user is an
organization user. Use \ to separate the organization name and the user name, for example, org1
\user1.
Accessing JReport Server Monitor
Only the root admin can log onto JReport Server Monitor and see both organization and nonorganization information.
Managing tasks
Usually, a task is a set of operations you perform on JReport Server to achieve a goal, such as
publishing a folder, deleting a resource, and viewing resource properties. However, the tasks that the
JReport Server manages are those associated with report-running issues, the report-running tasks.
JReport Server allows you to quickly view a report result (Run), view a report result using selected
options and parameters (Advanced Run), and schedule a report to run unattended at a specific time or
periodically (Schedule). These are the fundamental modes that JReport Server uses to perform its
report-running tasks.
You can view the status of these report-running tasks, such as scheduled tasks that are waiting to be
performed by JReport Server, the tasks that are currently being performed, and the tasks that have
already been performed.
This section describes the following:
●
Accessing the task information tables
●
Managing tasks in the task tables
●
Task-level timeout for advanced run and schedule tasks
Accessing the task information tables
JReport Server collects task information and manages it in a set of tables.
Tasks that are scheduled
●
❍
❍
❍
Scheduled table
Shows the status information of scheduled tasks that are waiting to be performed, such as task ID,
whether the task is enabled, previous running time, and next running time.
Running table
Shows the status information of tasks that are currently being performed, such as task ID, time
when the task was started, and engine status.
Completed table
Shows the status information of tasks that have already been performed, such as task ID, time
when the task was completed, whether or not the task was successfully performed, result files, and
error messages.
Tasks that are performed in the Run, Advanced Run or Background Run mode
●
❍
Background Tasks table
Shows the status information of the tasks submitted using the Run, Advanced Run, or Background
Run mode, such as report tab names, report path and name, catalog path and name, running
format, time when the task was started/completed, time elapsed since the task was performed,
and the status of the task.
To access a specific table, on the JReport Console page, click My Tasks on the system toolbar, then
click the corresponding tab. The following shows the columns that are displayed in each table in detail.
Tips:
●
●
Some columns in the tables are not shown by default. To have them displayed, switch to the table,
click Preferences on the task bar of the My Tasks page (for the Scheduled table, click Tools >
Preferences on the task bar), check the corresponding items in the Preferences dialog, then click
OK to save the settings.
You can make the records in each of the tables sorted ascendingly or descendingly by any column
title. To do this, just click on the underlined column title on which you want the records to be sorted,
you will then find a sort icon appear right after the title, showing the sort direction.
Scheduled table
The Scheduled table consists of the following columns:
Column
Description
Schedule Name
The name of the schedule task.
Task ID
The internal ID for this task, which is a unique time stamp.
Report
The report path, name and its status.
Report Tabs
The names of the report tabs in the report that are included in this task.
Next Run Time
The next scheduled time for when this task is to be performed.
Last Run Time
The last scheduled time this task was performed.
Task Type
The type of task, such as Versioning System, File System, E-mail, or Printer.
Is Enabled
Shows whether this task is enabled. Can be Enabled or Disabled.
Is Successful
Shows whether or not the last running of this task was successfully performed.
The value true means that the last running was performed successfully and false
means the task failed. If the column is empty, the task has not been run before.
Catalog
The catalog path and name that the report belongs to.
Launch Type
The way in which this task is executed, such as Repeatedly or One Time.
Requester
The user who submitted this task.
Running table
The Running table consists of the following columns:
Column
Description
Schedule Name
The name of the scheduled task.
Task ID
The internal ID for this task (a unique time stamp).
Report
The report path and name.
Report Tabs
The names of the report tabs in the report that are included in this task.
Start Time
The time when this task was started.
Task Type
The type of the task, such as Versioning System, File System, E-mail, or Printer.
Catalog
The catalog path and name that the report belongs to.
Launch Type
The way in which this task is executed, such as Repeatedly, One Time, or Instant.
Requester
The user who submitted this task.
Parameter File
The parameter file name. You can click the underlined file name to view the
parameter values.
Parameters
The list of parameter values according to the size specified.
To specify the size, click Preferences on the task bar, then in the Preferences
dialog, set a value for the Parameter Display Size option as required.
Engine Status
The current status of the JReport engine, such as record fetching, grouping,
memory paging, and engine initializing.
Completed table
The Completed table consists of the following columns:
Column
Description
Schedule Name
The name of the scheduled task.
Task ID
The internal ID for this task (a unique time stamp).
Is Successful
Shows whether this task was successfully performed. The value true means that
the task was performed successfully and false that the task failed.
Report
The report path and name.
Report Tabs
The names of the report tabs in the report that are included in this task.
Completed Time
The time when this task was completed.
Task Type
The type of task, such as Versioning System, File System, E-mail, or Printer.
Catalog
The catalog path and name that the report belongs to.
Launch Type
The way in which this task is executed, such as Repeatedly, One Time, or Instant.
Requester
The user who submitted this task.
Parameter File
The parameter file name. You can click the underlined file name to view the
parameter values.
Parameters
The list of parameter values according to the size specified.
To specify the size, click Preferences on the task bar, then in the Preferences
dialog, set a value for the Parameter Display Size option as required.
Engine Status
The status of JReport Engine when the task was completed, such as record
fetching, grouping, memory paging, and engine initializing. When a task fails to
perform, here you can see the status of the engine at the time of the error.
Error Message
The error message for when the task failed to complete the task.
Result Files
The report result file names and links to the report result files.
Background Tasks table
The Background Tasks table consists of the following columns:
Column
Description
Report Tabs
The names of the report tabs in the report that are included in this task.
Result
The result in the format in which the report ran.
Report
The path and name of the report that the report tabs belong to.
Start Time
The time when this task was started.
Finish Time
The time when this task was completed.
Status
The status of the task.
Catalog
The path and name of the catalog that the report belongs to.
Elapse Time
The time elapsed since the start of this task.
Catalog Version
Number
The version number of the catalog that the report belongs to.
Report Version
Number
The version number of the report.
Parameters
The parameters of the report.
Cancelled
Shows whether the task is cancelled or not.
Managing tasks in the task tables
You can manage tasks in the task tables according to your requirements. For example, you can run a
scheduled task at once, or stop a running task from running.
Performing common tasks
Some task management operations are common to the task tables.
If you want to
Then do
Select a task
Click in the row that the task is in.
Select multiple tasks
Select the rows that the tasks are in while holding the Ctrl button.
Remove a task
●
●
●
Select the row the task is in and click Edit > Delete on the task
bar of the My Tasks page.
Select the row the task is in, right-click in the row and select
Delete from the shortcut menu.
Put the mouse pointer over the row the task is in and click the
Delete button
on the floating toolbar.
Managing tasks in the Scheduled table
If you want to
Then do
Create a new scheduled task
Click New Schedule on the task bar of the My Tasks page, then in
the New Schedule dialog, specify how to create the task: by selecting
a report or by importing a script file.
Run a task at once
●
●
●
Select the row the task is in and click Run on the task bar of the
My Tasks page.
Select the row the task is in, right-click in the row and select Run
from the shortcut menu.
Put the mouse pointer over the row the task is in and click the
Run button
Duplicate a task
●
●
●
on the floating toolbar.
Select the row the task is in and click Edit > Copy on the task
bar of the My Tasks page.
Select the row the task is in, right-click in the row and select
Copy from the shortcut menu.
Put the mouse pointer over the row the task is in and click the
Copy button
on the floating toolbar.
Enable a task
●
●
●
Select the row the task is in and click Edit > Enable on the task
bar of the My Tasks page.
Select the row the task is in, right-click in the row and select
Enable from the shortcut menu.
Put the mouse pointer over the row that the task is in and click
the Enable button
Disable a task
●
●
●
on the floating toolbar.
Select the row the task is in and click Edit > Disable on the task
bar of the My Tasks page.
Select the row the task is in, right-click in the row and select
Disable from the shortcut menu.
Put the mouse pointer over the row the task is in and click the
Disable button
on the floating toolbar.
The disabled task will not be performed until you enable it again.
Export a scheduled task to a
script on disk
See Importing and exporting scheduled tasks for details.
Import a scheduled task from
a script saved on disk
See Importing and exporting scheduled tasks for details.
Notes:
●
●
You can perform the Run action on a disabled scheduled task.
When copying a disabled scheduled task or exporting it to script, the disabled state will not be
included since it is not a property of the task.
Managing tasks in the Running table
If you want to
Stop a task from running
Then do
●
●
●
Select the row the task is in and click Stop on the task bar of the
My Tasks page.
Select the row the task is in, right-click in the row and select
Stop from the shortcut menu.
Put the mouse pointer over the row the task is in and click the
Stop button
on the floating toolbar.
Note: When you stop a bursting task from running, some sub tasks
in the bursting task may have already been finished, so some results
may have been sent to some recipients.
View parameter information
Refer to the Parameters column of the Running table.
Managing tasks in the Completed table
If you want to
Then do
View detailed task running
information
●
●
●
●
Click the schedule name of the task.
Select the row the task is in and click Edit > Details on the task
bar of the My Tasks page.
Select the row the task is in, right-click in the row and select
Details from the shortcut menu.
Put the mouse pointer over the row the task is in and click the
Details button
View parameter information
on the floating toolbar.
Refer to the Parameters column of the Completed table.
Managing tasks in the Background Tasks table
If you want to
Stop a task submitted using
Background Run mode from
running
Then do
●
●
●
Select the row the task is in and click Edit > Stop on the task
bar of the My Tasks page.
Select the row the task is in, right-click in the row and select
Stop from the shortcut menu.
Put the mouse pointer over the row the task is in and click the
Stop button
Restart a stopped task
●
●
●
Select the row the task is in and click Edit > Restart on the task
bar of the My Tasks page.
Select the row the task is in, right-click in the row and select
Restart from the shortcut menu.
Put the mouse pointer over the row the task is in and click the
Restart button
View parameter information
on the floating toolbar.
on the floating toolbar.
Refer to the Parameters column of the Background Tasks table.
Task-level timeout for advanced run and schedule tasks
A task-level timeout mechanism is introduced in order to avoid the never-finished running tasks
consuming server resources and thus decreasing the server performance. With the mechanism, you
can specify a time duration for a task, and ask JReport Server to cancel the task or to notify you or
someone else of the task status via e-mail if the task has not yet finished running when the task
duration is up. To do this:
1. Do either of the following to enable the task-level timeout mechanism.
❍
❍
In the server.properties file, set the task.duration.enable property to true.
On the JReport Administration page, click Configuration on the system toolbar, select
Advanced, and then check the Enable Task Duration option.
2. Set task duration check frequency. By default, JReport Server checks task duration every 30
seconds. The period value can be reset either by the task.duration.check_cycle property in the
server.properties file or by the Status Refresh Interval option in the Configuration > Advanced
panel on the JReport Administration page. Note that the value must be an integer greater than 0.
Since task duration check frequency affects server performance, it is recommended that you set
the value according to your system environment.
3. Restart JReport Server if you have modified the Advanced panel.
4. Use the Duration tab in the Advanced Run and Schedule dialogs to specify task duration.
a. In the Timeout text box, specify the time limit for when the task can run before notifying of
the timeout or canceling the task.
b. If you want to notify someone of the task status if the task has not yet finished running when
the task duration is up, check Notify by e-mail after the specified time and specify the
mail address in the Mail To text box.
c. If you want JReport Server to cancel the task when the task duration is up but the task is not
finished yet, check Cancel the task after the specified time.
d. Click Finish to submit the task.
Then, when the specified task duration is up but the task has not finished running,
For an Advanced Run task,
●
❍
❍
If you have specified to have server cancel the task when the task duration is up, the task will be
cancelled automatically, however a record for the task will be still remained in the Background
Tasks table of the My Tasks page, shown with a sign of cancellation.
In the Duration tab, if you haven't checked the option Cancel the task after the specified time, the
task will be switched to run in background mode when the task duration is up, in which case, you
can choose to cancel the task manually. To do this, in the Background Tasks table,
■
Select the task row and click Edit > Delete on the task bar of the My Tasks page.
■
Select the task row, right-click in the row and select Delete from the shortcut menu.
■
Put the mouse pointer over the task row and click the Delete button
on the floating toolbar.
For a Schedule task,
●
❍
❍
If you have specified to have server cancel the task when the task duration is up, the task will be
cancelled automatically, and a task completed record will be added in the Completed table of the
My Tasks page, with the Is Successful status shown as No.
In the Duration tab, if you haven't checked the option Cancel the task after the specified time, the
task will still be listed in the Running table of the My Tasks page when the task duration is up.
Then, if you want to cancel the task manually, in the Running table,
■
Select the task row and click Stop on the task bar of the My Tasks page.
■
Select the task row, right-click in the task row and select Stop from the shortcut menu.
■
Put the mouse pointer over the task row and click the Stop button
on the floating toolbar.
Notes:
●
●
JReport Server may not cancel a task right after the specified task duration is up due to check
frequency.
It is recommended that the task duration is set to about five times of the required time for finishing
running the task.
Managing server data
During its running process, JReport Server keeps track of server information and stores it to its own
database for the purpose of running various managing and monitoring tasks, such as managing the
resources on the server, monitoring the task running status, and collecting server running statistics.
The server database includes system, realm, and profiling. The system database holds resources of the
global server scope, such as server.properties, global NLS, etc. The realm database holds information
of folders, nodes, versions, the security system, and the completed table. The profiling database holds
server runtime related information. You can refer to Configuring the server database for details about
how to configure the databases.
JReport provides completed SQL files to create tables for all databases supported. They reside in
<install_root>\script_files.
This section covers the following topics:
●
Initializing the database system as a non-admin database user
●
Checking server data integrity
●
Backing up/restoring server data
●
Archiving and restoring server data
●
Viewing the summary information of archive files
●
Clearing unused nodes from the realm database
Initializing the database system as a non-admin database user
The database initialization system allows you to use a non-admin database user for JReport Server.
However, the database initialization has to be divided into three phases:
1. The database administrator creates new database tables using script files.
2. The non-admin database user starts JReport Server. In this phase, the old version's database
tables will be updated if they exist. If the server has updated the old version's table data, you will
be able to see a record of it in the debug file.
3. The database administrator deletes the old version' tables in the database using script files.
Script files
JReport Server supports these different databases: Apache Derby, HSQLDB, MySQL, Microsoft SQL
Server, IBM DB2, Oracle, Sybase, and Informix.
The script files are stored in <install_root>\script_files. There are three types of script files:
Script files used for creating new database tables
The following files are used to create new database tables, and are stored in <install_root>
\script_files\create_new_tables:
●
db2_c.txt - Creates new tables for DB2 database.
●
derby_c.txt - Creates new tables for Derby database.
●
hsqldb_c.txt - Creates new tables for HSQLDB database.
●
informix_c.txt - Creates new tables for Informix database.
●
mysql_c.txt - Creates new tables for MySQL database (for single-byte charset, e.g latin1).
●
mysql_mb2_c.txt - Creates new tables for MySQL database (for MBCS two-byte charset, e.g. gbk).
●
mysql_mb3_c.txt - Creates new tables for MySQL database (for MBCS three- byte charset, e.g.
utf8).
●
oracle_c.txt - Creates new tables for Oracle database.
●
sqlserver_c.txt - Creates new tables for Microsoft SQL Server database.
●
sybase_c.txt - Creates new tables for Sybase database.
Script files used for deleting the old version' tables
The following files are used to delete the old version' tables, and are stored in <install_root>
\script_files\delete_old_tables:
●
db2_do.txt - Deletes old version tables for DB2 database.
●
derby_do.txt - Deletes old version tables for Derby database.
●
hsqldb_do.txt - Deletes old version tables for HSQLDB database.
●
informix_do.txt - Deletes old version tables for Informix database.
●
mysql_do.txt - Deletes old version tables for MySQL database.
●
oracle_do.txt - Deletes old version tables for Oracle database.
●
sqlserver_do.txt - Deletes old version tables for Microsoft SQL Server database.
●
sybase_do.txt - Deletes old version tables for Sybase database.
Script files used for deleting the current version' tables
The following files are used to delete the current version' tables, and are stored in <install_root>
\script_files\delete_current_tables:
●
db2_dc.txt - Deletes current version tables for DB2 database.
●
derby_dc.txt - Deletes current version tables for Derby database.
●
hsqldb_dc.txt - Deletes current version tables for HSQLDB database.
●
informix_dc.txt - Deletes current version tables for Informix database.
●
mysql_dc.txt - Deletes current version tables for MySQL database.
●
oracle_dc.txt - Deletes current version tables for Oracle database.
●
sqlserver_dc.txt - Deletes current version tables for Microsoft SQL Server database.
●
sybase_dc.txt - Deletes current version tables for Sybase database.
Checking server data integrity
In abnormal circumstances, server data may not be saved correctly or completely in the databases.
JReport Server allows you to check the integrity of server data.
The integrity check mainly examines two aspects of the realm database:
●
●
Integrality and consistency among tables - checking records among the tables to see whether they
are complete and consistent.
Integrality and consistency between realm database and the external files - checking to see whether
the records in the tables match the related external files.
If any inconsistent or incomplete server data is found, it will be removed from the realm database since
it is unused. The same process also applies to files.
To check server data integrity, do one of the following:
●
Launch JReport Server on the command line, using parameter -cleanup.
C:\JReport\Server\bin>JRServer -cleanup
●
Open the batch file used to start JReport Server, add -Dcheck.realmtables=true to the line that
starts JReport Server:
"%JAVAHOME%\bin\java.exe" -Dcheck.realmtables=true "-Dinstall.root= <install_root>" ...
Note: The integrity check checks only the realm database.
Backing up/restoring server data
Backing up server data
The server data backup process inspects all of the tables in the database, collecting and then exporting
all table data to a ZipEntry. For certain tables, such as the catalog version table, report version table,
and report result version table, the data also includes relational real files from the history directory. All
server data is compressed to a single Zip file, and all table data and every relational real file is stored
as a ZipEntry in this single file.
You have two alternatives for exporting the server data: through the server user interface or through
command line.
Exporting the server data through the server user interface
1. On the JReport Administration page, click Data on the system toolbar and then select System DB/
Realm DB/Profiling DB from the drop-down menu.
2. Select a realm if it is the Realm DB or Profiling DB panel.
3. Click the Backup tab, type the file path and name in the Backup System DB/Realm DB/Profiling
DB field (or use the Browse button to specify the file path), and then click Backup. Note that the
file extension should be included.
Exporting the server data through the command line on Windows or on Unix/Linux
A tool is provided to backup the server data. It is DBMaintain.bat/DBMaintian.sh in <install_root>
\bin. It has two parameters:
●
-Bsystemtables/-Brealmtables/-Bprofiling: Backup the data with the server data in a JReport cluster.
●
-B0realmtables: Only backup the data in the database.
To export the server data from the command line on Windows or on Unix/Linux:
1. In a DOS window, switch to the <install_root>\bin folder.
2. Use the DBMaintain command (DBMaintain.sh on Unix/Linux) and -Bsystemtables/-Brealmtables/Bprofiling or -B0realmtables parameter. For example:
C:\JReport\Server\bin>DBMaintain -Brealmtables:C:\TEMP\cmd_b_realmtables.dat Bprofiling:C:\TEMP\cmd_b_profiling.dat
Restoring server data
The server data restore process picks up all table data from the backup file and inserts it into the
corresponding table in the database. You can only restore server data using the DBMaintain tool with
the -Rsystemtables/-Rrealmtables/-Rprofiling or -R0realmtables parameter.
To import server data using the command line:
1. In the DOS window, switch to the <install_root>\bin folder.
2. Use the DBMaintain command and -Rsystemtables/-Rrealmtables/-Rprofiling or -R0realmtables
parameter, for example:
C:\JReport\Server\bin>DBMaintain -Rrealmtables:C:\TEMP\cmd_b_realmtables.dat Rprofiling:C:\TEMP\cmd_b_profiling.dat
Backup/restoration limitations
The backup/restore feature does not support cross-platform operation. The backup and restore
operations must be done on the same operating system. For example, if you backup the server data to
a zip file on a Windows platform, you will then not be able to restore it on a Unix system.
Notes:
●
●
●
●
On the JReport Administration page, the Profiling DB option is not shown by default on the Data dropdown menu. To make it shown, you need to set the server.profiling.enable property to true in the
server.properties file in the <install_root>\bin directory.
When running DBMaintain.bat/DBMaintian.sh, error may occur if the backup zip file is too large,
which is caused by JVM limitation. You can try the -B0realmtables and -R0realmtables options to
backup and restore data separately.
When backing up server data in cluster environment, it is recommended that you back up the data
on every cluster node to make sure no files get lost on any node after they are restored. Also, the
system DB and realm DB should better be backed up together. Since the external data cannot be
backed up once just on one single cluster node, to avoid redundant data backup, you need to
manually back up the external files on every cluster node after backing up the system DB and realm
DB on any of the cluster nodes.
When restoring server data in cluster environment, first make sure all the cluster nodes are shut
down, and then restore the data on each cluster node.
Archiving and restoring server data
You can archive and restore server data in the realm and profiling databases.
Archiving server data
Along with the running of the server, the sizes of the result version table (DB: realm) and TaskContext
table (DB: profiling) grow larger. JReport Server allows you to archive data to a single backup file. You
can then retrieve the data from the backup file at a later date.
To archive the server data:
1. On the JReport Administration page, click Data on the system toolbar and then select Realm DB/
Profiling DB from the drop-down menu.
Note: The Profiling DB option is not shown by default on the drop-down menu. To make it
shown, set the server.profiling.enable property to true in the server.properties file in the
<install_root>\bin directory.
2. Select a realm from the Select Realm drop-down list.
3. Switch to the Archive tab.
4. Specify a date in the Move to Archive Data Before field, and then type or use the Browse button
to specify the file path and name.
If you don't want to backup the archived server data, leave this field blank. The server data will
then be removed from the database.
5. Click Archive. Server data prior to the date specified will be archived and saved to the backup file
using the name specified.
Restoring the archived server data
You can restore server data that has been archived from a backup file. You can only restore it using the
server user interface.
To restore the archived server data:
1. On the JReport Administration page, click Data on the system toolbar and then select Realm DB/
Profiling DB from the drop-down menu.
2. Select a realm from the Select Realm drop-down list.
3. Switch to the Archive tab.
4. Type or use the Browse button to provide the archive file name and location in the Restore from
archive field, and then click Restore.
Viewing the summary information of archive files
After archiving or backing up files, you can view the results. The summary information includes
Archive, Date, Type, Version, Realm, Database and Scope.
To view the summary information of a specified file:
1. On the JReport Administration page, click Data on the system toolbar and then select Realm DB/
Profiling DB from the drop-down menu.
Note: The Profiling DB option is not shown by default on the drop-down menu. To make it
shown, set the server.profiling.enable property to true in the server.properties file in the
<install_root>\bin directory.
2. Select a realm from the Select Realm drop-down list.
3. Switch to the Summary tab.
4. Type or use the Browse button to specify an archive file name and location in the Archive field,
and then click Summary.
Clearing unused nodes from the realm database
Making operations on real path resources may generate unused nodes from the realmdatabase. The
generated unused nodes can be cleared through the JReport Administration page.
How unused nodes are generated
When resources, such as folders, catalogs, and reports, have been published using a real path in order
to allow dynamic updating there is a possibility to produce invalid nodes. After running a report and
saving the result to the versioning system or scheduling reports which are saved in the versioning
system, either of the following conditions will generate invalid nodes:
●
Cancel or change the real path setting.
●
Publish a resource to replace an existing real path resource.
How to clear invalid nodes
To clear unused nodes:
1. On the JReport Administration page, click Data on the system toolbar and then select Realm DB
from the drop-down menu.
2. Click the Realm DB Check tab.
3. Click the Check button. All invalid resource nodes will then be listed.
4. Check the checkbox on the header of the first column to specify whether you want to select all or
unselect all. Otherwise, you can check the corresponding checkbox to select the invalid nodes that
you want to delete.
5. Click Delete button to delete all selected nodes.
Managing cached report data
Cached report data (CRD) is a cached subset of data fetched from the database according to certain
conditions and is used as a substitute for the database for retrieving data for reports. This provides
several benefits.
●
●
●
●
Reports can be run from a specific point in time such as a month end report or quarter end report
without going back to the DBMS to get the original data.
Many users can run reports from data created from a single query without impacting production
DBMS users.
Users running a report will all see the same view of the data, thus the data will not change minute
by minute based on current DBMS updates.
Caching report data can be scheduled for any time frame to simulate real time on-demand reporting
for many users while not slowing down the production DBMS.
Cached report data can be created for data sources including queries, stored procedures, imported
SQLs, user defined data sources, hierarchical data sources, and parameters whose type is Bind with
Single Column or Bind with Cascading Columns. All these types of data sources will be called query
resources for convenient documentation since they will be mentioned a lot in the following sections.
There are two types of cached report data in JReport Server: auto CRD and scheduled CRD.
Auto CRD
When running a report, if there is no scheduled CRD created for the query resource that the report is
using directly or indirectly (for example, the report is created based on a report cube and the report
cube is built from a query resource), data will be fetched from the data source, and at the same time
the fetched data is cached and becomes an auto CRD.
When there are auto CRDs generated in a query resource, the report running request based on the
query resource will first search for the auto CRD that contains all the data required by the report. If it
finds one, the located CRD will retrieve data to the report, but if JReport cannot find one, data is
fetched from the data source and cached to be another auto CRD.
Auto CRDs will only be available within one server running life cycle, which means that once the server
closes or restarts, they will be removed and a new cycle of auto CRD generation will begin. How many
auto CRDs can be held in a query resource within one server running session is decided by the
maximum hard disk space configured in the Cache Configuration dialog.
Auto CRDs are disabled for generation by default. You can enable them and configure the maximum
hard disk space for auto CRDs and how long an auto CRD is stored. For details, see the Automatic
Cache section in the Cache Configuration dialog.
Scheduled CRD
Scheduled CRDs can be created and managed by server administrators. A query resource can have
zero or one scheduled CRD. When a query resource contains parameters, its scheduled CRD can only
represent the data of one parameter scenario.
Via JReport's scheduling mechanism, administrators are able to define when a scheduled CRD for a
query resource will be created and how it will be updated according to time. Scheduled CRDs have no
version: once they are updated, only the latest are kept in the query resource.
Creating scheduled CRDs
Administrators can schedule to have a data cache created for a query resource and updated at a
specific time or periodically. When scheduling a CRD task, more than one query resource can be
selected at a time and a CRD can be created for each query resource and all of the scheduled CRDs will
be applied the same creation and updating policy.
1. On the JReport Administration page, click Cache on the system toolbar and then select Data
Cache from the drop-down menu.
2. On the Cached Report Data tab, click New Cache on the task bar.
3. In the New Cache dialog for selecting queries, click
next to the Select a Folder text field.
4. In the Select Folder dialog, browse to the folder containing the required catalog and click OK.
5. From the Select a Catalog drop-down list, select the required catalog in the specified folder.
6. Click
beside the Select Queries box.
7. In the Select Queries dialog, select the query resources you want to create data caches for from
the resource tree. Then click OK.
8. Click OK in the New Cache dialog for selecting queries and you are then redirected to the New
Cache dialog for scheduling.
9. In the General tab, you can specify values to the parameters of the query resources listed in the
Select Query drop-down list. If no values are provided, the default values will be applied. The
query resource names will be used as the new CRD names.
10. Specify the other settings in the tab if needed.
11. In the Conditions tab, specify the time for when the task is to be performed in the Time sub tab,
and select or create a trigger to bind with the task in the Trigger sub tab. The setting in the
Conditions tab decides when the CRDs will be created and when they will be updated.
12. In the Notification tab, specify to notify someone via e-mail when the task is finished and whether
it is successful or unsuccessful.
13. Click Finish, and JReport Server will then perform the task at the requested times.
See also New Cache dialog for details about options in the dialog.
Using scheduled CRDs
A scheduled CRD has four statuses. Whether reports running based on the same query resource as the
CRD can fetch data from the CRD is determined by the CRD's status.
●
Not ready
CRD is not initiated yet. The reports will try to get data from the data source directly.
●
●
●
Initiating
CRD is preparing its data for the first time, but still not ready. The reports will wait for the CRD to be
ready and then fetch data from the ready CRD.
Ready
CRD is prepared and ready to use. All reports based on the same query resource will fetch data from
the CRD.
Updating
CRD is updating itself at a scheduled point. All reports based on the same query resource will use the
ready CRD before the update happens. Once the update is finished, later reports will get data from
the updated CRD.
After a scheduled CRD is created and ready to use, all reports based on the same query resource as the
CRD will automatically use the CRD for retrieving data.
Since a scheduled CRD freezes parameters in the query resource, if a report uses a scheduled CRD and
its query resource contains parameters, when running the report, only parameters used in the report
are available for specifying values and the query resource parameters will be disabled for editing. In
JReport, a parameter may depend on another parameter; if the latter is frozen, the former will be
frozen as well.
Editing scheduled CRDs
The generated scheduled CRDs are displayed in the Cached Report Data tab.
You can further edit the scheduling information of the CRDs if required. To do this, select the row in
which the CRD you want to edit is located, then click Edit > Properties on the task bar or right-click
on the row and select Properties from the shortcut menu. If parameters or schedule policy is changed,
they will only take effect after the next CRD update; before that, all reports using the CRD will still get
the old data.
In addition, if you find any of the scheduled CRD is no longer required, you can remove it. To do this,
select the row where the CRD is, then clicking Edit > Delete on the task bar; or right-click in the row
and select Delete from the shortcut menu.
Viewing and managing scheduled CRD tasks
CRD tasks that are waiting to be performed are listed in the Scheduled tab. To access the tab, click
Cache > Data Cache on the system toolbar and then go to the Scheduled tab.
CRD tasks that are currently being performed are listed in the Running tab. To access the tab, click
Cache > Data Cache on the system toolbar and then go to the Running tab.
CRD tasks that have already been performed are listed in the Completed tab. To access the tab, click
Cache > Data Cache on the system toolbar and then go to the Completed tab. You can remove the
record of a completed CRD task from the tab if required. To do this, select the row where the record is
located and then click Delete on the task bar, or right-click on the row and select Delete from the
shortcut menu.
For details about the tabs, refer to Data Cache panel.
Recovering scheduled CRDs
Scheduled CRDs will be recovered after the server shuts down and then restarts. The data before the
shutdown will be maintained.
If a CRD is updating when the shutdown happens, the CRD will continue with the update when the
server restarts.
Synchronizing scheduled CRDs with catalog republish
After a catalog is republished, how the existing scheduled CRDs based on the old query resources in
the catalog will be updated depends on the following conditions:
●
●
If no query resource is modified, the existing CRDs will be automatically applicable to the new
catalog.
If a query resource is modified, the scheduled CRD based on the old query resource will behave as
follows:
❍
❍
Before the next schedule time, the CRD will be disabled for retrieving data to reports.
When it is the next schedule time, data is fetched from the new query resource to generate an
updated scheduled CRD:
■
■
■
If new parameters are added in the new query resource, default values will be used until an
administrator specifies values to them.
If old parameters are deleted from the new query resource, the parameter values previously
specified in the CRD will be removed.
If parameters are changed and the previously specified values do not match the type, error
messages will be given in the server error log and the CRD is disabled for service.
Configuring the CRD memory usage
Administrators can configure the maximum CRD memory in the Cache Configuration dialog, which is
applicable for both types of CRDs (to access the dialog, focus on the Cached Report Data tab, then click
Cache Configuration on the task bar). The value should be at least 4 MB and not more than 80% of
the JVM current maximum heap size. The number of MBs must be configured in whole numbers. The
cache is used to improve performance when multiple users are running reports using the same CRD.
Any size CRD can be accessed with even the smallest cache size. The larger the cache size the faster
performance will be for concurrent users, but a large cache size may lower performance for users who
do not use the CRD. All CRDs share the same cache area.
If possible, set the maximum memory usage to a number that the memory can handle, for example,
512 MB or bigger.
Managing in-memory cubes
In-memory cubes are cached data of business views. The generating and updating of in-memory cubes
are achieved by scheduling cube tasks. In-memory cubes are similar to scheduled reports that can be
run immediately, run once at a specific time or run periodically to select the data from the DBMS and
store it in JReport Server. After an in-memory is created and ready for use, all web reports, library
components, and visual analyses that use the same business view as the in-memory cube will
automatically use the cube rather than go to the database for the data. By applying in-memory cubes,
your reporting performance will be greatly improved.
This section shows how to create, use and manage in-memory cubes as follows:
●
Creating in-memory cubes
●
Viewing and managing the cube tasks
●
Recovering and synchronizing in-memory cubes
Creating in-memory cubes
A business view can have only one in-memory cube. When a business view contains parameters, its inmemory cube can only represent the data of one parameter scenario. However, if you want the inmemory cube to be available to Visual Analysis, the cube should contain all of the parameters in the
business view.
Via JReport's scheduling mechanism, administrators are able to define when an in-memory cube for a
business view will be created and when it will be updated at a specific time or periodically. In-memory
cubes have no versions: once they are updated, only the latest one is kept for the business view.
If it is the first time to create in-memory cubes, the administrator needs to first configure the
maximum memory allowed for all in-memory cubes.
To configure the maximum memory for in-memory cubes:
1. On the JReport Administration page, click Cube on the system toolbar.
2. In the Cube panel, click Configuration on the task bar.
3. In the Cube Configuration dialog, specify a value no larger than 80% of your Java Heap size for
the Maximum Cube Memory Allowed option.
4. Click OK.
It can also be specified by the property server.cube.maxmemory in the server.properties file in the
<install_root>\bin directory.
To create an in-memory cube:
1. On the JReport Administration page, click Cube on the system toolbar.
2. In the Cube panel, click New Cube on the task bar.
3. In the New Cube dialog for selecting business view, click
next to the Select a Folder text field.
4. In the Select Folder dialog, browse to the folder containing the required catalog and click OK.
5. From the Select a Catalog drop-down list, select the required catalog in the specified folder.
6. In the Select Business View box, select the business view on which to create the in-memory cube.
7. Click OK and you are then directed to the New Cube dialog for scheduling.
8. In the General tab, you can specify values to the parameters of the business view if there are any.
If no values are provided, the default values will be applied. The business view name will be used
as the new in-memory cube name. Specify the other settings in the tab if needed.
9. In the Schedule tab, specify the time for when the task is to be performed in the Time sub tab,
and select or create a trigger to bind with the task in the Trigger sub tab. The setting in the
Schedule tab decides when the in-memory cube will be created and when it will be updated.
10. In the Settings tab,
a. In the Maximum Memory Allowed text box, provide a value for the cube. The value must be
specified, otherwise you are not allowed to continue with other tabs or to finish the dialog.
b. If you would like to cache the cube on disk once the available memory is exhausted, select
Move the cube to disk if insufficient memory was allocated. If this option is not
selected and the memory is not enough for the cube, the cube status will be disabled and an
error will be shown in the log tab.
c. If you would like the detail data in the business view to be cached onto disk, select Cache
Detail on Disk. Otherwise if you need only the aggregation data to be cached, unselect the
option.
11. In the Notification tab, specify to notify someone via e-mail when the task is finished and whether
it is successful or unsuccessful.
12. Click Finish, and JReport Server will then perform the task at the requested times.
See also New Cube dialog for additional information about options in the dialog.
After an in-memory cube is created and ready for use, all web reports, library components and visual
analyses based on the same business view as the cube will automatically use the cube for retrieving
data.
Since an in-memory cube freezes parameters in its related business view, if a report uses an inmemory cube and its business view contains parameters, when running the report, only parameters
used in the report are available for specifying values and the business view parameters will be disabled
for editing. In JReport, a parameter may depend on another parameter; if the latter is frozen, the
former will be frozen as well.
Viewing and managing the cube tasks
You can view information of the tasks scheduled for creating in-memory cubes and manage the tasks in
the following tabs.
Schedule tab
All scheduled cube tasks are listed in the Schedule tab (to access the tab, click Cube on the system
toolbar and then go to the Schedule tab), which consists of the following columns:
Column
Description
Name
The name of the cube task.
Catalog
The catalog that the cube belongs to.
Data Source
The data source that the cube belongs to.
Status
The task status:
●
●
●
●
●
Pending
The cube has no data and is waiting to run based on scheduled policy. The
cube is not ready for use.
Building
It is the first time creating the cube and filling data to the cube. The cube is
not ready for use.
Updating
It is updating cube data based on the scheduled policy. The cube is not ready
for use.
Completed
Cube data is available. The task will not be updated any more according to
the scheduled policy.
Disabled
The cube is not allowed to generate or update following the scheduled policy.
The cube data cannot be used or released.
Create Time
The time when the scheduled task was created.
Next Run Time
The next time when the scheduled task will generate or update the cube.
Last Run Time
The last time when the scheduled task generated or updated the cube.
Times Run
The number of times the scheduled task has generated or updated the cube.
If the number is bigger than 0, click it and you will be able to view the details of
each running of the cube, including all updating events since the cube was
generated. The detail table contains the following columns:
Column
Description
Activity
Shows the type of the event.
●
●
Build
Indicates that the cube was created.
Update
Indicates that the cube was updated.
Start Time
Shows the time when the event started.
End Time
Shows the time when the event ended.
Status
Shows whether the event is successful.
●
●
Successful
Indicates that the event is successful.
Failed
Indicates that the event failed.
You can edit any of the cube tasks in the Schedule tab in the following ways:
●
To further edit the scheduling information of a task, select the row in which the task is located, then
on the floating toolbar, or
click Edit > Properties on the task bar, or the Properties button
right-click on the row and select Properties on the shortcut menu. In the displayed dialog, edit the
scheduling information. If parameters or schedule policy is changed, they will only take effect after
the next cube update; before that, all reports using the cube will still get the old data.
●
To disable a task that is not disabled, select the row where the cube task is, then click Edit >
Disable on the task bar, or the Disable button
and select Disable on the shortcut menu.
●
To enable a task that is disabled, select the row where the cube task is, then click Edit > Enable on
the task bar, or the Enable button
Enable on the shortcut menu.
●
on the floating toolbar, or right-click on the row
on the floating toolbar, or right-click on the row and select
To remove a task that is no longer required, select the row where the cube task is, then click Edit >
Delete on the task bar, or the Delete button
and select Delete on the shortcut menu.
on the floating toolbar, or right-click on the row
Active tab
All the cube tasks that have generated in-memory cubes which have data and are ready for use are
listed in the Active tab (to access the tab, click Cube on the system toolbar and then go to the Active
tab), which consists of the following columns:
Column
Description
Name
The name of the cube task.
Catalog
The catalog that the cube belongs to.
Data Source
The data source that the cube belongs to.
Updated Time
The last time when the cube was updated.
Allocated
The maximum memory allowed for the cube.
Actual
The memory size currently used by the cube.
Located At
Shows the location of the cube:
●
●
Parameter
On Disk
Indicates that the cube is swapped to the disk.
In Memory
Indicates that the cube is in the memory.
Displays a parameter icon. By clicking the icon a dialog will appear to show all
the parameters used in the cube.
Usage
The number of reports and library components that have accessed the cube. If
the number is bigger than 0, click it and you will get a detail table showing the
information of all the web reports and library components that used data from
the cube.
The detail table contains the following columns:
Column
Description
Name
The name of the web report or the library component that used the cube.
Type
Indicates whether it is a web report or a library component.
Dashboard
The name of the dashboard that is using the library component. For library
components only.
User
The user who ran the web report or the library component.
Description
The description about the web report or the library component.
In the Active tab, you can also edit the tasks in the same way as you do in the Schedule tab.
Log tab
All the events happened on all the cube tasks are recorded in the Log tab (to access the tab, click Cube
on the system toolbar and then go to the Log tab), which consists of the following columns. The
number of the records allowed in the tab is controlled by the property "server.cube_log.max_count".
The default number is 3000.
Column
Description
Name
The name of the cube task.
Catalog
The catalog that the cube belongs to.
Data Source
The data source that the cube belongs to.
Activities
The type of the event:
●
●
●
●
●
●
●
Create
The cube was created.
Edit
The cube was edited.
Initiate
The cube data was initiated and made usable.
Update
The cube data was updated.
Disable
The cube was disabled.
Enable
The cube was enabled.
Delete
The cube was deleted.
Start Time
The time when the event started.
End Time
The time when the event ended.
Status
The event status:
●
●
Message
Successful
The event was successful.
Failed
The event failed.
Messages for failed events.
You can delete any of the log records from the tab if you want. To do this, select a record row and then
click Edit > Delete on the task bar, or the Delete button
the record row and select Delete on the shortcut menu.
on the floating toolbar, or right-click on
Tip: Some columns are not shown by default in the three tabs. To have them displayed, focus on the
required tab, click Preferences on the toolbar, check the corresponding items in the Preferences
dialog, and then click OK to apply the settings.
Recovering and synchronizing in-memory cubes
Recovering in-memory cubes
If an in-memory cube is updating when the server shuts down, the cube will be disabled after the
server restarts. Administrators need to enable the cube task in order for the cube to continue to update
at the next scheduled time.
Synchronizing in-memory cubes with catalog republish
After a catalog is republished, how the existing in-memory cubes based on the old business views in
the catalog will be updated depends on the following conditions:
If no business view is modified, the existing in-memory cubes will be automatically applicable to the
new catalog.
If a business view is modified, the in-memory cube based on the old business view will behave as
follows:
Before the next schedule time, the cube will be disabled for retrieving data to reports.
●
●
When it is the next schedule time, data is fetched from the new business view to generate an
updated cube:
❍
❍
❍
If new parameters are added in the new business view, default values will be used until an
administrator specifies values to them.
If old parameters are deleted from the new business view, the parameter values previously
specified in the cube will be removed.
If parameters are changed and the previously specified values do not match the type, error
messages will be given in the server error log and the cube is disabled for service.
National Language Support
JReport products implement a National Language Support (NLS) feature, with which you can run
JReport Server, Page Report Studio, Web Report Studio, JDashboard, reports, or dashboards in
different language environments.
This chapter is split into two topics:
●
NLS at application level
●
NLS at report level
Related topics:
●
Appendix 6: Language and Region name list for National Language Support
NLS at application level
In JReport Server, a folder "resources" is added in the installation root directory for holding language
packages. Each language package contains all the UI text and messages available in JReport Server,
including Page Report Studio, Web Report Studio, and JDashboard, and specifies the UI text in a
specific language. When a language package is applied, the UI will be displayed in the language
specified in the language package. When there are more than one language packages, you can select
the one you are familiar with for your own convenience as the JReport Server environment language.
For example, if you are a German you may be glad to apply the German language package.
Moreover, when creating a WAR/EAR file to include a JReport Server, the languages.jar which packs all
language resources in the <server_install_root>\resources directory will be generated and
included for the multiple language support. The languages.jar makes sure the server UI text is
displayed correctly after deploying the WAR/EAR to other application servers.
Manually adding a language package
Currently JReport provides only the English language packages: en and en-us. However, JReport
accepts user-customized language packages and can recognize and load them if they are correctly
specified, though it may be a big task.
In each language package, there are four property files which together contain all UI text and
messages in JReport Server, Page Report Studio, Web Report Studio, and JDashboard:
●
●
●
common.properties
This property file stores some common UI text all over JReport Server in the specific language.
dhtml.properties
This property file stores UI text and messages referred by Page Report Studio, Web Report Studio,
and JDashboard in the specific language.
server.properties
This property file stores UI text and messages referred by JReport Server in the specific language.
The structure of a language package which is stored in the <server_install_root>\resources\server
\languages directory follows:
\LanguageName
\properties
common.properties
dhtml.properties
server.properties
To add a language package, follow the steps below:
1. Browse to the <server_install_root>\resources\server\languages directory.
2. Create a folder named fr. The folder name should keep to the naming criterion.
3. Copy the properties folder in the existing <server_install_root>\resources\server\languages
\en directory to the \fr folder.
4. Modify the three property files: common.properties, dhtml.properties, and server.properties in the
\fr folder. Translate all the text and messages after "=" in these files to French.
5. Save these property files with UTF-8 encoding.
6. Convert the contents in the three property files into Unicode using native2ascii.exe in the
<jdk_install_root>\bin directory by running the following line in the Command Console:
C:\jdk1.6.0_17\bin>native2ascii -encoding utf-8 common.properties >newcommon.
properties
C:\jdk1.6.0_17\bin>native2ascii -encoding utf-8 dhtml.properties >newdhtml.
properties
C:\jdk1.6.0_17\bin>native2ascii -encoding utf-8 server.properties >newserver.
properties
Note: When you convert your property files to the same directory as the original ones you
need give them new names instead of replacing the original in order to avoid problems.
7. Rename the original property files, you may want to modify them more at a later time.
8. Change the names of the generated property files back to the same names as the original
property files: newcommon.properties to common.properties, newdhtml.properties to dhtml.
properties, and newserver.properties to server.properties.
9. Restart JReport Server.
Naming criterion for language package folders
* FolderName(language)
* FolderName(language-country)
* FolderName(language-country-variant)
The folder name should be lower-case codes.
The language argument is a valid ISO Language Code. These codes are the lower-case two-letter codes
as defined by ISO-639. You can find a full list of these codes at a number of sites, for example: http://
www.ics.uci.edu/pub/ietf/http/related/iso639.txt.
The country argument is a valid ISO Country Code. These codes are the lower-case two-letter codes as
defined by ISO-3166. You can find a full list of these codes at a number of sites, for example: http://
www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html.
The variant argument is a vendor or browser-specific code. For example, use win for Windows, mac for
Macintosh, and posix for POSIX. Where there are two variants, separate them with an underscore, and
put the more important one first.
Specifying the application language
Once the application language is set, it takes effect in the whole JReport Server, including Page Report
Studio, Web Report Studio, and JDashboard. There are two ways of setting the application language:
Specifying by UI option
●
There is an option Specify Default Language for you to switch the application language. The available
language list depends on the language packages in <server_install_root>\resources\server
\languages.
To specify the application language:
❍
❍
For administrators, on the JReport Administration page, click Profile on the system toolbar, select
Customize Server Preferences from the drop-down menu, then click the Advanced tab and set
the default application language for all users.
For end users, on the JReport Console page, click Profile on the system toolbar, then click
Customize Server Preferences on the task bar of the Profile page, select the Advanced tab and
set an application language for themselves.
Specifying by URL parameter
●
End users can control the application language by the parameter jrs.language when accessing the
JReport Console page or Page Report Studio UI via URLs. The format of the URL is as follows:
http://IP_Address:port/context/pagename?parameter=value&jrs.language=Language_Name
The value of jrs.language should be the same as the language package folder name in the
<server_install_root>\resources\server\languages directory and be lower-case letters.
The following are two examples:
❍
URL for accessing the JReport Console page:
http://127.0.0.1:8888/jinfonet/index.jsp?jrs.language=zh-cn
❍
URL for opening a page report in Page Report Studio:
http://127.0.0.1:8888/dhtmljsp/dhtml.jsp?jrs.cmd=jrs.try_vw&jrs.report=/
SampleReports/EmployeeInformation.cls&jrs.catalog=/SampleReports/SampleReports.
cat&jrs.cat_version=1&jrs.path=/SampleReports/EmployeeInformation.cls&jrs.
result_type=8&jrs.language=zh-cn
Note: The specified application language by URL parameter has higher priority than that specified by
UI option; however, it takes effect only in the current user session.
NLS at report level
If the NLS feature is enabled for a report or library compnent when it is designed in JReport Designer,
it will also be available after the report or library compnent has been published to JReport Server (for
detailed information about how to use the NLS feature in JReport Designer, see National Language
Support in the JReport Designer User's Guide). Then, when the report or dashboard that contains the
library compnent runs in the client/server scenario, different clients can select different languages to
render it. Also, JReport provides you with the NLS Editor on JReport Server, with which you can edit
NLS for any report or library compnent the same as the report designer does in JReport Designer, and
what's more, you can create global NLS resources that can be shared by all reports and library
compnents to reduce the translation cost.
Note: The NLS feature is not supported on chart components in web reports and dashboards at present.
The following topics show how to use the NLS feature in JReport Server:
●
Creating global NLS
●
Editing local NLS
●
Running NLS reports/dashboards
●
Localizing page navigation links in HTML report outputs
Creating global NLS
The global NLS is similar to the local NLS feature. Local NLS is the NLS resource used for a particular report or library component, while
global NLS is the NLS resource that can be used for all reports and library components in any catalog in both JReport Server and
JReport Designer. With global NLS, you can share the NLS information between all reports and library components and reduce your
translation cost. This feature is provided to administrators only.
To create global NLS on JReport Server:
1. Start JReport Server and log onto the JReport Administration page.
2. Click Resources on the system toolbar and select Global NLS from the drop-down menu.
3. Click the Add button
above the Language box. The Select Language Source dialog is then displayed.
4. Specify where to add the required languages.
❍
❍
Languages Supported by JReport
Adds languages from the languages that JReport supports.
NLS Resource File
Adds languages from an external NLS resource file which has been defined with some language information.
NLS resource files should follow the naming rule: NLS_[language]_[region A2]_[User Defined].properties. Refer to Appendix 6:
Language and region name list for National Language Support for language and region A2 codes.
5. Click OK in the Select Language Source dialog. Then,
❍
❍
If Languages Supported by JReport is checked in the dialog, the Add Language dialog will be displayed. Select the required
languages and click OK to add them.
If NLS Resource File is checked in the dialog, the File Upload dialog will be displayed. Browse to the local folder where the NLS
resource file is located, select the file and then click Open.
The specified languages are now displayed in the Language box in the Global NLS dialog.
6. Select a language from the Language box to edit global NLS for it.
7. In the Display tab, click the Add button
to add a new row of display. Select the type of the display from the Type drop-down
list, specify the key in the Key column, then give the corresponding target language text in the Translation column. Click
add more rows and specify the key and translation according to your requirements.
to
8. In the Font tab, click the Add button
to add a new row of font. In the Key column, choose from the drop-down lists the font
face and font size of the key, in the Font Face column, choose from the drop-down list the font face for the target language, then
in the Font Size column, choose from the drop-down list the font size for the target language or check to use relative font size.
Click
to add more rows and specify the font information according to your requirements.
9. Repeat the above steps to define global NLS for the other languages as required.
10. When done, click OK to accept the settings.
See also the Global NLS dialog for detailed explanation about options in the dialog.
Editing local NLS
JReport allows you to edit NLS for each report or library component on the Administration page of JReport Server as the report
designer would with the NLS Editor in JReport Designer. With the NLS Editor, you can translate a report or library component into
different languages from the original one. This feature is provided to administrators only.
To edit NLS for a report or library component on JReport Server:
1. Start JReport Server and log onto the JReport Administration page.
2. In the resource tree, browse to the report/library component you want to edit.
3. Select the row that the report/library component is in, then click the NLS Editor button
Editor dialog appears.
in the Control column. The NLS
4. Specify a report/component and catalog version as required.
5. Click the Add button
above the Language box.
6. In the Add Language dialog, select the languages in which you want the report/library component to display, then click OK to
confirm and go back to the NLS Editor dialog.
7. The selected languages are now listed in Language box of the NLS Editor dialog. Select a target language from the box to edit
NLS for it.
, then in the Add Display dialog, where all the display text in the report/library component are
8. In the Display tab, click
listed, add the display text you want to translate and click OK. Then, enter all the corresponding target language text in the
Translate column. If you have defined global NLS for the target language, you can also click Fetch from Global NLS to fetch
the corresponding display information. If required, click Add to Global NLS to add the display information you just specified to
the global NLS library of the target language.
9. Switch to the Format tab, click
, then in the Add Format dialog, where all the formats used in objects of the report/library
component are listed, add the formats you want to customize and click OK. Then, provide the corresponding format in the
Format column for the target language.
10. Click the Font tab, click
, then in the Add Font dialog, where all the fonts used in objects of the report/library component
are listed, add the fonts you want to