ADVANTAGE SOFTWARE FACTORY

NextReports

User Guide
Version 8.1
 NEXTREPORTS

User Guide

 Advantage Software Factory

169 Calea Floreasca 6th floor, Sect. 1, Bucharest, Romania
www.next-reports.com
www.asf.ro
next_support@asf.ro
Phone +40 21 242.87.20 • Fax +40 21 242.87.22
Table of contents

1. Introduction ...................................................................................................................................1
1.1. What is NextReports ...........................................................................................................1
1.2. System Requirements..........................................................................................................2
1.3. Conventions ........................................................................................................................2
2. Installation .....................................................................................................................................3
3. Usage ..............................................................................................................................................7
3.1. Menu Bar ............................................................................................................................9
3.2. Shortcuts Bar .....................................................................................................................15
3.3. Object Explorer Panel .......................................................................................................16
3.4. Data Sources .....................................................................................................................21
3.5. Parameters .........................................................................................................................25
3.5.1. Create a new parameter ............................................................................................... 25
3.5.2. Add an existing parameter .......................................................................................... 29
3.5.3. Runtime values............................................................................................................ 30
3.5.4. Dependent parameters ................................................................................................. 31
3.5.5. Parameters with “ALL” value ..................................................................................... 32
3.5.6. Special __USER__ Parameter .................................................................................... 32
3.6. Query Designer .................................................................................................................34
3.7. Query Editor......................................................................................................................37
3.8. SQL Log Panel ..................................................................................................................40
3.9. Status Bar ..........................................................................................................................41
3.10. Report and Chart creation ...............................................................................................41
3.11. Wizard .............................................................................................................................42
3.12. Report Layout .................................................................................................................51
3.13. Alarm Reports .................................................................................................................68
3.14. Indicator Reports .............................................................................................................70
3.15. Display Reports ...............................................................................................................71
3.16. Report Templates ............................................................................................................73
3.17. Chart Layout ...................................................................................................................74
3.18. Publish & Download .......................................................................................................80
4. Advanced Topics .........................................................................................................................82
4.1. Internal Structure ..............................................................................................................82
4.2. Configuration ....................................................................................................................83
4.3. Adding support for your language ....................................................................................87
4.4. Adding support for other JDBC driver .............................................................................88
4.5. Annex ................................................................................................................................91
 1
Chapter

1. Introduction
This paper describes the installation process and the usage of NextReports software application.
To read about how to use it you can go directly to chapter 3 Usage.

1.1. What is NextReports

NextReports is a free software application which allows creating sql queries, reports and charts on
some data sets from a database. Next image shows the general process of report or chart creation.

Briefly, NextReports application connects to a database through a jdbc driver (see chapter 3.Usage,
Data Sources Section). A user creates a sql query which can contain or not some parameters. This
query can be written directly inside an editor for those users which are accustomed to SQL
language, or can be designed using the NextReports designer. (See chapter 3.Usage, Editor Section
and Designer Section).

In next step, the user creates report layout. This layout specifies every element’s position inside the
report, the properties – font, background color, foreground color, font style, pattern, padding,
borders and so on. The report can be exported in one of the NextReports supported formats (pdf,
excel-xsl, excel-xlsx, docx, rtf, text-csv, tsv, web-html, xml and txt). (See chapter 3.Usage Report
Layout Section).

1
 Introduction

User can also create a chart layout selecting chart type, X and Y axis columns, legends, colors,
pattern and many other properties. The chart can be previewed inside NextReports designer
application, but its main purpose is to be published to a NextReports server where it can be viewed
in real-time. (See chapter 3.Usage Chart Layout Section) or to be inserted inside a report (See 3.12.
Report Layout).

1.2. System Requirements

NextReports Application can run on any platform which supports Java 6 (See chapter
2.Installation). It was successfully tested on Windows 2000, Windows XP, Windows Vista,
Windows 7, Linux (Ubuntu). It was not tested on Mac OS, Sun Solaris, Windows 95, Windows ME
but it should run without problems on these operating systems.

On Linux a Window Manager (KDE, Gnome) must be installed.

1.3. Conventions

Some conventions used in this paper.

Italics
Text written in italics is changeable and must be replaced with something specific indicated in the explanation.
Italics style can be used to emphasize some words or to make some reference on other documents (books, web sites).

Bold
Text written in bold is used to show something of importance, to indicate menu names and graphic components inside
an application frame.

fixed font
Text written in fixed font is used to show the characters that must be entered, the messages that the system returns,
default values or file names.

File > Save

This shows a menu selection. For example, select File menu, then select Save option.

ATTENTION
This shows that you can obtain unexpected results if you do not follow the instructions.

2
 2
Chapter

2. Installation
NextReports application can be downloaded from http://www.next-reports.com .
If a version of NextReports is already installed, you can run Help -> Check for update action which
will do the download process automatically.

The selected NextReports file for download must be chosen depending on the user operating
system and on the version of java installed on the computer.

For Windows and Linux there are native installers, files with .exe or .sh extensions (see next image
from installation process).

For any other operating system there is a generic installation file with .zip extension.

3
 Installation

To test the existence of JVM (Java Virtual Machine) on your computer, you have to open a
command line terminal (a DOS prompt in Windows or a shell in UNIX) and to enter the following
command:

java -version

You will see a text like the following:

java version "1.6.0_21"

Java(TM) SE Runtime Environment (build 1.6.0_21-b07)
Java HotSpot(TM) Client VM (build 17.0-b17, mixed mode, sharing)

This will show that there is a JVM installed on the computer. If the version is newer than 1.6.0 you
can download an installation file which does not contain the JVM (and is smaller because of that)
(for example next-reports-setup-3.4.exe for Windows users).

If you have a version older than 1.6.0 or if you receive the following message:

java: Command not found.

This means that you do not have the required java version installed on the computer and you must
choose for download a setup file with JVM inside (for example next-reports-setup-3.4-jre.exe for
Windows users)

After the setup file was downloaded, if it is a native installer for Windows or Linux, you can
execute it directly to install NextReports on the computer.

If it is a generic installation file with .zip extension, you have to unzip the archive to a folder, and
run the corresponding operating system file: run.bat or run.sh.

For native installers, after selecting the installation folder, user has to select the http port used by
NextReports application to preview charts.

4
 Installation

User can check to see it the default http port is free. If it is, a green background will be shown and
we can move to the next step. Then, the start menu folder is selected and the installation process is
started. Last step will confirm that installation was successful and will allow starting the
application.

5
 Installation

ATTENTION Starting with 5.3 version, all user data like saved data sources, schemas,
queries, reports, charts, generated files, templates, logs are kept inside user home
folder in a location .nextreports-<ver> where <ver> is the version of NextReports
designer. If you will want to import data from a previous version you will have to
select this folder for any version greater or equal than 5.3, or the installation folder for
any version less or equal than 5.2. .nextreports-<ver> folder is kept intact when
NextReports designer is uninstalled.

6
 3
Chapter

3. Usage
To help for an easy understanding of NextReports usage, the installer contains a Demo database (a
Derby embedded database) with a sql query and a report.
There are also some online tutorials at http://www.next-reports.com which show the basic
functionalities of NextReports application.

Next image shows the main frame of the application.

7
 Usage

Right away after the NextReports is started, inside the main frame we can see the following zones:

- Menu Bar (1)

- Shortcuts Bar (2)
- Object Explorer Panel (3)
- Parameters Panel (4)
- Query Designer (5)
- Query Editor (6)
- Sql Log Panel (7)
- Status Bar (8)

This window represents the query perspective, the place where the user creates the sql query.

A query represents a select on a data set from a data source, saved inside a file with .query
extension. A query can be created in two ways. The first way is using the graphic designer (5),
through drag-and-drop and selection actions without the need of knowing SQL language. The
second way is writing the query inside the NextReports editor using SQL language (6).

A report is constructed on a sql query by specifying a layout, the way that it will show through
font, colors, padding, borders and so on. The report can be exported in one of the following
NextReports supported formats: html, excel xls and xlsx, pdf, docx, rtf, csv, tsv, xml or txt. The
report is saved in a file with .report extension. After a report creation, the main frame will show the
report layout perspective where the user can modify the properties of all report layout elements.
(See Report Layout section)

A chart is constructed on a sql query by specifying a layout with it’s type, axis columns and all the
properties that define the mode it will look like colors, font, format, legends. Charts can be
previewed as HTML5 / flash, meaning the browser will be opened with a HTML5 / flash object, or
as an image. A chart is saved in a file with .chart extension. After a chart creation, the main frame
will show the chart layout perspective where the user can modify the properties. (See Chart
Layout section). When a chart is inserted inside a report, the generated file will contain the chart as
an image. When the chart is added on the server inside a dashboard, it is shown in real time as
html5 / flash.

On the left side of the main frame for query perspective there are two tabs: one for the object
explorer panel and one for the parameters panel. By clicking left mouse button on those, we can
select / unselect if the tabs are shown or not. If only one of the panels is visible, to make the second
one visible and keeping also the first, we must keep the SHIFT key pressed when we select it with
the mouse. The vertical order of the two panels can be changed by drag-and-drop with the mouse.

Next, we will present every zone from the application.

8
 Usage

3.1. Menu Bar

Menu Bar contains the NextReports actions thematically grouped (File, Perspective, Tools, Help).
Every action has a tooltip which shows simple information about its purpose.

File menu contains general actions for creation, open and save entities.

Next we will briefly describe all File menu actions:

New menu has the following actions :

- Data Source… allows the addition of new data sources inside the application

- Query cleans the designer panel and the editor, so that the user can start from beginning to
create a new query.

- Report creates a new report from the current loaded query

- Report From Query … creates a new report from a selected query.

- Chart creates a new chart from the current loaded query

- Chart From Query … creates a new chart from a selected query.

9
 Usage

Open menu contains:

- Query … opens a query created previously by NextReports.

- Report opens a report previously created by NextReports.

- Chart opens a chart previously created by NextReports.

- Return to Parent Report opens the parent report of the current one

Import menu contains :

- Data Sources … allows the import of one or more data sources from an xml file created
through an export action. If there is a data source with that name inside the application, to
keep the name unique, the new data source will contain at the end the date when it was
added.

- Query… imports a new query created by a NextReports application for the connected data
source.

- Report … imports a report generated by a NextReports application for the connected data
source.

- Chart … imports a chart generated by a NextReports application for the connected data
source.

Export menu contains :

- Export Data Sources … allows the export of one or more data sources to an xml file. Such a
file can be send to another NextReports user (by email for example) and the user can
import that file and use the new data sources.

10
 Usage

ATTENTION Even the database password is encrypted, we recommend using some

safe ways to transfer the exported xml file.

Favoritesmenu contains all favorite entities (reports and charts) that were added as favorites,
followed by a “Remove favorites” action:

When a favorite entry is clicked, NextReports will automatically connect to favorite data source
and the favorite entity (report or chart) will be loaded inside designer.

Save saves the current opened query/report/chart. If the query/report/chart was loaded or
previously saved, the action will be executed on the opened document.

Save As… saves the current opened query/report/chart to a new file

Exit this
action will allow to close the application. The same action is done by clicking the close
button (on top right) of the main frame. If a query or a report is opened, the user will be notified
and asked if he wants to save the current document.

Perspective menu contains the following actions :

- Query allows the visualization of query perspective.

- Layout allows the visualization of layout (report or chart) perspective.

Tools menu contains the following actions :

- Wizard … this action starts the wizard of report/chart creation (see Wizard Section).

- Publish… this action publishes the current report/chart to a NextReports server

- Download… this action downloads the selected report/chart from a NextReports server

- View SQL allows viewing the sql query from the selected query/report/chart without loading
the entity.

11
 Usage

- Templates menu contains :

- Create Template creates a new report template (See Template Section).

- Modify Template … modifies a report template (See Template Section).

- Apply Template …applies a template to the current loaded report (See Template Section). It is
enabled only when a report is opened.

- Extract Template extract

the template from the current loaded report(See Template Section) .
It is enabled only when a report is opened.

- Backup … allows to backup all the configuration data and all generated data to a zip archive.
It is recommended to make backups periodically to keep your data safe.

- Restore … allows restoring data from a zip archive file created previously through a backup
action.

ATTENTION On every restore, existing NextReports structure (configuration files,

data sources, schemas, queries, reports) will be lost. Because of that, it is
recommended to make a Backup before any Restore.

- Import … allowsimporting data sources and all queries, reports and charts from an older
version of NextReports

12
 Usage

ATTENTION This operation can be performed for older versions of NextReports

starting with 2.0. See installation chapter for what folder to select.

- Settingsallows to modify NextReports configuration properties (like connection timeout,

query timeout, html accessibility, fonts folders, oracle client folder, csv delimiter, A4 limit
warning, ruler visibility and ruler measure unit)

- Reset Layout allows to restore the initial layout of the application frame

- menu is active only when a report or a chart is loaded. This action allows
Internationalization
internationalizing text from report /chart.

User defines some keys, the languages and enters the values of those keys for every language.
One language must be set as default, and this is the language used at run time inside designer.
On the server side, the report will be run with the Locale language (set from settings) or, if that
language is not found between report’s defined languages, with report default language.

13
 Usage

To use a key inside report layout, it has to be embraced by @@ markup. As an example if user
has a key named title and he wants to use it as report title inside a text cell, the actual text must
be @@title@@ .

For reports, besides static text, user can enter keys inside cell’s pattern properties, expressions
and parameters runtime names. For charts, keys can be used for title, description, legends,
tooltips and parameters runtime names.

ATTENTION If some keys are used inside expressions, internationalization is applied

after those expressions are evaluated. This allows for internationalizing fields from
database using expressions like “@@” + $C_<column> + “@@” .

- Language menu contains actions for changing the current language used in application. You
can choose between Romanian, English and French. By default, after installation, the
application starts in English.

Help menu contains some general actions.

Next we will briefly describe all Help menu actions:

- Check for update allows searching for a new NextReports version.

- Tutorial opens the browser to see online tutorial movies.

- Manual opens the browser to see online manual

- Quick Start showsthe startup panel. Keeping the checkbox ‘Show at startup’ checked will
make this panel to be visible at every startup.

- About Next-Reports allows viewing application information

14
 Usage

3.2. Shortcuts Bar

In this place we can find shortcuts for some actions from the menu bar.

Here there are in the following order actions from NextReports menus:

- New Query
- Save

- Wizard
- Publish

- Open Query Perspective

- Open Layout Perspective

- Return to parent report

If a query is opened, « Open Layout Perspective » action is disabled. If a report or a chart is

opened, « Open Layout Perspective » is enabled.

If edit chart or edit report actions from inside another report are used « Return to Parent Report »
becomes enabled and shows the name of the parent report.

See previous section Menu Bar for more explanations.

15
 Usage

3.3. Object Explorer Panel

“Explorer” Panel contains hierarchically the following types of objects:

- data sources (1)

- database schemas (2)
- database tables (3)
- database views (4)
- database procedures (5)
- queries (6)
- reports (7)
- charts (8)
- folders (9)

Inside the menu bar there are the following actions:

- Refresh reloads the queries and reports nodes for the connected data source
- Expand all expands all explorer nodes
- Collapse all collapses all explorer nodes

NextReports application can contain any number of data sources, but only one is active (connected)
at a time. The connected data source will be shown in the explorer with and its name will be
printed in the left corner of the status bar.

We can execute different actions on the nodes from the explorer panel. For example, on a data
source node by a mouse right click we can do one of the following:

16
 Usage

Depending on the status of the data source (connected or not) some actions are active or inactive.
For example, if the data source is connected we can do the following actions Disconnect, View and
Schemas but there are inactive Connect, Edit, Delete. For a disconnected data source only the action
Disconnect is inactive.

For a database table or view we can see the column information by double-clicking on the selected
object or by mouse right click and selecting View. A panel like the next will be shown:

Columns marked by are primary keys, those marked by are foreign keys and those marked by
are indexed columns.

For a database procedure object the following actions can be done:

- View Columns Info: this is similar to column information for tables and views
- Validate Procedure: this action will test if the selected procedure is a valid procedure for
NextReports, meaning a report can be created from it. (see QueryEditor section for more
information)

‘Validate Procedure’ action can be called also on ‘Procedures’ node from explorer, meaning all
procedures from the connected database will be tested for validation.

17
 Usage

For Tables, Views and Procedures group nodes there is also a ‘Name Pattern’ action. This pattern is
kept only for the database connection lifetime and it is used by the tree when nodes are expanded.
An empty or % pattern means all values. This pattern is useful when database contains thousands of
tables, views or procedures and you know what entities you want to use by their names. By
selecting a pattern the time to load entities will be significantly slower.

For a query object with mouse right click we can see the following actions:

- Open Query
- New Report From Query …
- New Chart From Query…
- Delete Query
- Rename Query
- Export Query …
- Validate Sql : informs user if selected query has a valid sql (an sql which can run without
errors)

If there is at least an invalid sql, a message will show the user the corresponding error. If there are
modified table names or column names, user is allowed to do a bulk replacement on all invalid
entities. Replace process is case sensitive.

For a report object with mouse right click we can see the following actions:

- Open Report
- Delete Report
- Rename Report

18
 Usage

- Export Report
- Run Report (to html, excel xls and xlsx, pdf, docx, rtf, csv, tsv, xml, txt) without open it
- Publish Report to a NextReports server
- Validate Sql : informs user if selected report has a valid sql (an sql which can run without
errors)
- Add to favorites: report will be accessible from Favorites Menu

For a chart object the following actions are possible:

- Open Chart
- Delete Chart
- Rename Chart
- Export Chart
- HTML5 Preview Chart without open it
- Flash Preview Chart without open it
- Image Preview Chart without open it
- Publish Chart to a NextReports server
- Validate Sql : informs user if selected chart has a valid sql (an sql which can run without
errors)
- Add to favorites: chart will be accessible from Favorites Menu

When a query, report or chart is opened the relative path can be seen in the main title bar.

In addition we can import queries, reports or charts generated by another NextReports application
by mouse right clicking on the Queries, Reports and Charts nodes. For Queries, Reports and Charts root
objects we can also Add folder . Such objects are physical folders on disk. We can add, delete ,

19
 Usage

rename folders and import a query, report, chart from an external source. NextReports allows for
drag & drop queries, reports, charts and folders to any other folder from the explorer. A simple drag
& drop will move the object. A drag & drop with CTRL pressed will copy the object.

Validate Sql action can be done on Queries, Reports and Charts nodes or on any folder inside these.
This means sqls from all queries, reports or charts found under that node will be tested for
validation. If some sqls are invalid, the nodes will have their icons drawn with a warning bullet.

From explorer tree we can also perform some bulk actions like Publish or Download.

If reports or charts root is selected, we can select Publish action to publish to server a set of reports /
charts. The difference between this action and the Publish action for a single report / chart is that
when we have only a report, information like server path, data source are stored locally and reused
when we publish again the same report / chart.

When reports root, charts root or any folder is selected we can perform a bulk Download action. All
selected reports / charts from server will be downloaded to the selected folder. The Download
action from menu bar allows selecting only one report / file and, in addition to bulk download,
allows saving it with another name.

20
 Usage

3.4. Data Sources

To be able to create a query or a report, you need a data source.

NextReports application can contain any number of data sources, but only one is active
(connected) at a time.

To create a data source select File > Add Data Source … from the menu bar or with mouse right click
on Connections node and select Add Data Source ... from Explorer panel.

Next information is needed to create a new data source (see next image) :

Name field (1) is mandatory and represents the data source name. There cannot be two data sources
with the same name inside NextReports application.

Type field (2) is the type of the database to which we will connect. The user can select one of the
following types: NextReports Server, Oracle, Oracle-Service, Oracle-Tns Name,MySQL,
MSSQL Server, Derby Embedded, Firebird, SQLite, Vertica, Pervasive, CsvJDBC..
To connect to a database we need a jdbc driver. Such a driver is a software component (a file with
jar extension) which allows to a java application to interact with the database. A different jdbc
driver is needed for any type of database.
In folder <NEXTREPORTS_HOME>\lib (where <NEXTREPORTS_HOME> is the
NextReports installation folder) there are some jdbc drivers that are installed by the application.

Driver field (3) is mandatory and represents the name of the driver java class.

21
 Usage

URLfield (4) is mandatory and represents the information needed to locate the database to which we
want to connect.

Every jdbc driver has a standard format for this field. The format is printed in bold under field (4) –
for example mysql has the following format jdbc:mysql://<ip>:<port>/<database> where the
information between < and > will be replaced with particular values. These values (database
parameters) can be easily modified by clicking the button from the right of url field.

User field (5) is the name of the user used to connect to the database.

Password field (6) is the password used to connect to the database.

(7) is not a persistent field. It just informs the user, that after data source
Auto connect after save
creation / modification, the connection to it will be done automatically (if it is checked).

After all the fields are entered, before saving the data source, it is useful to test the connection to
the database by clicking the button Test.
If the connection is valid, then we will see some information about the database in the zone Status
(8) like the database type, database version, driver name, driver version.
If the connection is invalid and cannot be established an error message will be printed in (8).
In the case of error, you have to verify the fields entered and to verify the physical connection with
the computer where the database is stored – network, firewall (if necessary). For connection
creation there is a timeout specified in application settings. If that timeout expires a
TimeoutException will be shown.
The data source can be saved by clicking the button Save and after that it will be shown in the object
explorer panel under the Connections node.

After creation of a data source we can connect to it (mouse right click on the data source node and
select Connect from the shown popup menu). After connection is made , in the object explorer
panel, under the data source node will appear the visible schemas with tables and views, and also
the nodes Queries and Reports where all created queries and reports will be found.
After a data source creation only the default schema is visible. If the user wants to work on other
schemas, these can be selected from the popup menu of the explorer panel , Schemas option. After
selection, the new schemas will be visible in the object explorer panel.

22
 Usage

Csv JDBC driver

NextReports contains a special JDBC driver which allows to connect to CSV files. To create a CSV
data source, user has to select such driver:

Data source url contains the directory path where csv files are found. For CSV data sources user
can edit driver properties:

User must choose the file extension and the separator character. Other properties are not
mandatory. If CSV file contains on the first row the column names separated by comma, then
nothing else has to be chosen. If CSV file does not contain column names, then user has to select
suppress headers property and must enter their names (separated by comma) inside column

23
 Usage

names property. User can also select the types for columns. By default they are all String. User can
choose between String, Int, Double, Boolean and Date.

ATENTION Generally, a CSV data source will be associated with a single CSV file, especially
in case of editing column names and their types. Column names must not be selected from
SQL function names (SUM, AVG, MIN, MAX, COUNT, LOWER, UPPER, ROUND). A
query can be done on a single CSV file (there is not possible to create JOINS between two or
more CSV files).

‘NextReports Server’ special driver

Some customers do not want to allow access to their databases from outside. In that case, you can
obtain access using NextReports Server. NextReports Server must be installed on a machine inside
customer’s network. In designer we can define a data source with ‘NextReports Server’ driver type.
To edit the url for this kind of driver, you have to enter user and password used to connect to
server. Url contains a NextReports Server and a data source which is selected from existing data
sources on the server.

24
 Usage

3.5. Parameters
Sometimes the data set must be filtered when you want to create a sql query or a report. This can be
done inside NextReports by using parameters.

Parameters can be managed in the panel with the same name. Here we can add new parameters, we
can modify parameters, we can delete them or we can change the order in which they will appear at
query/ report runtime (1).

The navigation inside the panel can be done with the ↑ (up) and ↓ (down) keys.

To modify a parameter, select the parameter in the panel and press ENTER key (or double-click or
press the button from the toolbar). A panel like the one shown when you add a parameter will
be shown on the screen.

It is possible to clone a parameter using action. A new parameter with the same properties as the
selected one, but with the name appended with ’_c’, will be created.

To delete a parameter, select the parameter in the panel and press DELETE key (or press from
the toolbar).

To modify the order in which parameters are shown at query or report runtime, select the parameter
in the panel and use one of the following actions , from the toolbar.

3.5.1. Create a new parameter

To add a new parameter, press the button . A new panel with information that defines the
parameter will be shown. (see next images). The General tab contains:

Name field (1) is mandatory and cannot contain spaces. There cannot be two parameters with the
same name inside a query or report. Inside the query, the parameter will appear like ${name} and it
will be substituted at runtime with the value(s) selected by the user.

Runtime name (2) is the name that user will see when the query or the report is executed.

25
 Usage

Source field (3) represents the source of data used to get the possible values for the parameter at
runtime. If nothing is specified , the user can enter any value at query runtime. (a text field
component).

If you want that a parameter to take its values from database table (view) column, then click the
button . In this case a panel like the following will be shown on the screen.

26
 Usage

There are three columns. In the first one (from left to right) there are all the tables and views in the
selected data source for the schema that is selected above. When a table or view is selected in the
first column, in the columns two and three will be seen all the columns of that table (view). The
user can select the desired column from second column.
There are some cases when the user wants inside the query to use as a parameter value as an id, but
in the runtime panel to be shown to enter an associated name (because he does not know the id
value). In such a case the user must select from the second column the id column and from the third
column the name column. Technically we may say that the parameter has pairs of Id-Name values.

If a parameter must take its values from a query then the button must be used. A panel with a
sql editor will appear on the screen.

Any SQL query of type “SELECT <expr1>, <expr2> FROM …” will be allowed, where <expr1>
represents the id column and <expr2> is the name column selected when button is clicked,
situation previously described. <expr2> is optional. If both expressions are present in the select,
the values returned by query can be ordered by id or by name. If only <expr1> is present, the values
are ordered after id.

If you want to delete the source of parameter values , you can click the button .

Type field (4) represents the data type of parameter. The following values are allowed: Integer, String,
Boolean, Byte, Date, Timestamp, Time, Double, Float, Long, Short, Object.
Default value is String (text). In case of source selection (3) the parameter type will be automatically
selected by the application and the user will not be allowed to modify it.

Selectionfield(5) can be Single or Multiple and represents the selection mode of parameter at runtime.
Single means the user will select only a value. Multiple means the user can select one or more
values.

Mandatory field (6) specify if the selection/introduction of a parameter value is mandatory at

runtime. If this checkbox is selected and at runtime the user does not enter a value for the
parameter, a message that informs the user about this situation will be shown and the query / report
is not executed.

Description field (7) is optional. Here the user can enter a parameter description.

27
 Usage

The ‘Default‘ tab contains the default values the parameter can take. Those values can be added by
hand to a list (2) or can be taken from an sql source (3) . If the parameter has default values, those
values will be selected at runtime. If parameter is checked as hidden (1) the parameter will not be
seen at runtime, and it’s values will be compute and set at the moment the query is executed. For
example if you need a hidden parameter that is substituted at every run with the current date, you
can edit the source with “select sysdate from dual” for Oracle data source. For current date you do
not have to know the format of the select for the data source, because a template button inside the
source dialog will auto complete that value.

The ‘Procedure’ tab contains properties for stored procedure support.

Used field (1) shows if the parameter is used by a stored procedure. (see Query Editor section)

field (2) is the value that the procedure used internally to exit as fast as possible
Preview value
making the process of finding the return columns faster. (see Query Editor section)

28
 Usage

3.5.2. Add an existing parameter

To add an already created parameter you can use the button from toolbar. A new dialog will be
shown.

29
 Usage

First, you have to select a query, report or chart. On selection, the list of parameters will be shown
on the right. By double-clicking on a parameter, a parameter information dialog will appear were
you can see its properties.

After you decide what parameters you want to add to your new report, you have to select them and
click Ok.

3.5.3. Runtime values

Next image shows, as an example, the runtime parameters panel with the values that those
parameters can take.

The parameters that take their values from a database and have Single selection will be shown as a
combobox through which only a value can be selected. Those who have Multiple selection will be
shown as a dual list through which any number of values can be selected. With CTRL-A we can
select all the values from a list.

The parameters that do not take their values from database, can have Single or Multiple selection.
Their values will be entered by the user. For single selection type, if their data type is Boolean they
will appear as a checkbox. If their data type is Date they will appear as a calendar. For all other data
types, the parameters will be shown as a text field. For multiple selection type, user can add to a list
more values. If values are strings or numbers, it is possible to add more of them at once by using
semicolon delimiters. If values are dates, it is not possible to add more values at once because the
component used is a calendar not a text field.

For example, we notice that the parameter with Runtime name Name was declared as a parameter
which takes its values from a table / view column and its Selection is of type Multiple (more values
allowed at runtime). Also, the parameter with Runtime name Start Date is of type Date and because
of that the start date it will be selected from a DatePicker calendar component.
Mandatory parameters will be identified in the runtime panel if they have the character * before
their name.

30
 Usage

3.5.4. Dependent parameters

If a parameter takes its values from a query , there is the possibility to use inside that query another
parameter which will be specified between the tags ${ and }. The parameter defined this way is
dependent on the parameter(s) used inside the query. At runtime a parameter dependent on another
parameters will have its values loaded only after all parameters it depends on are selected by the
user.

Example:

select distinct t.employeeid, e.name from timesheet t, employee e

where t.employeeid = e.employeeid
and t.projectid in ${Project}

This query is valid only if a parameter with the name Project was defined.

31
 Usage

ATTENTION The selection type of the parameter used inside the query must be related to
the operator used before it in the query.

For the previous example the selection is Multiple. If we use equality inside the query , for
example :

select distinct t.employeeid, e.name from timesheet t, employee e

where t.employeeid = e.employeeid
and t.projectid = ${Project}

Project parameter must be defined with Single selection type.

3.5.5. Parameters with “ALL” value

If a parameter is not mandatory, and no value is entered for it at runtime, then null will be passed as
its value. To simulate an “ALL” value you have to do two things :

- in parameter manual source you have to add the “All” value , you must use an id (not used
in database).

Example: manual source for CLIENT_NAME parameter. The name is specified as –ALL—
to appear the first in parameter value selection.

Select client_id, name from clients

UNION
Select -100,'-- ALL --' from dual

- interpret the “All” value id in the sql where clause

Example:
and (${CLIENT_NAME} = ce.client_id or ${CLIENT_NAME} = -100)

3.5.6. Special __USER__ Parameter

Sometimes your reports and charts used on server must show filtered data for current logged user.
To accomplish this task you will have to define in your report or chart a special parameter with
name __USER__ (it has two underscores in front and two at the end). NextReports Server will
know about this parameter and it will fill its value with the current logged user name. Because you
do not want the logged user to change the value of the parameter, this parameter must be defined as
hidden. Also this parameter has Type = String and Selection = Single.

You have to use this parameter in your query or inside another not-hidden parameter. To use it
inside the query see 3.6. Query Designer chapter. If you create your query with Query Editor you
will use the parameter as any other like this:

32
 Usage

…..
WHERE
USER_NAME = ${__USER__}
…..

There is also the possibility to use __USER__ parameter inside the source of other parameter and to
not use it at all inside the main query. For example think about a not-hidden parameter PROJECT
to show all the projects to which the current logged user is their project manager. In this case, the
PROJECT parameter must have a source to filter data like in the following example:

select project_id from projects p, users u

where p.project_manager_id = u.user_id and
u.user_name = ${__USER__}

ATTENTION To be able to run the query from the designer you have to put a default value
or a default source for __USER__ parameter. (Keep in mind that its value is set on the
server!).

33
 Usage

3.6. Query Designer

To create a query there is the possibility of using a designer.

After the connection to a data source is opened, an user can add the tables and the views needed by
the query in the tab Query Designer through drag-and-drop. After column selection, in the table
beneath (criteria panel) will appear some rows.

From designer toolbar the user can specify if the query select is distinct or not, can add a group, can
clean the designer and can run the query. The run action will move the user to the editor panel to
see the results. In the bottom right corner of the designer panel there is a button through which
the user can select what to see in the designer (rectangle selection) without using the scrolls. This
button is shown only if the both scrolls are visible.

Between two tables the user can create joins in two ways. The user selects a column in one table
and then drag the mouse to a column in the other table. Another possibility is that of Auto-Join. On
every key (primary or foreign key) from a table with the mouse right button a popup menu with this
option is shown. By selecting it, the application will search automatically all the columns in other

34
 Usage

tables that can be joined to the selected one. The join line has a button . By clicking it the join can
be modified : we can modify the operator and specify an extern join. With the mouse right click on
the join button , this join can be deleted.

The criteria panel contains the selected columns. Here we can specify for every column an alias, if
it is visible or not in the runtime result, sorting type, sorting order, a group and a criteria.

A criteria can be added with mouse right click and by selecting from the popup menu the option
Add Criteria.

35
 Usage

A criteria for the selected column contains an operator and one or two values (depending on
operator type). The values can be entered by the user or specified by the values of some parameters.
For example, for DATA column we wish the value to be between two dates by using the
BETWEEN operator and two parameters whose values will be entered at runtime.

User can add an ‘or criteria’ through option Add Or Criteria similar as adding a criteria. Such criteria
will be saved under the column ‘Or’. The generated select will contain an OR between all simple
criterias and all ‘or criterias’.

Inside criteria panel we can add also expressions with the mouse right click and selecting from the
popup menu the option Add Expression. An expression is useful for cases in which we cannot select
just a column from a table (view). We can enter any valid expression for the used database.

For example, an expression can be a simple concatenation of two columns with a space between
them , that is done in Oracle like this : FIRSTNAME || ' ' || LASTNAME. For expressions it is
recommended to specify an alias , otherwise the column name in the result will be the row number
from the criteria panel.

Also from the criteria panel, the user can modify the order in which the columns appear in
the query. To move a column, we select the row, keep SHIFT key pressed and drag-and-drop
the row with the mouse.

In the criteria panel , on the top right, there is a button which will open a popup menu from where
we can select/unselect the columns from the criteria panel and also their packed size.

Criterias and expressions can be modified with the mouse right button and selecting from the popup
menu Edit Criteria , Edit Or Criteria and Edit Expression respectively. Also criterias and expressions can
be deleted with the mouse right button and selecting from the popup menu the action Delete Criteria,
Delete Or Criteria and Delete Expression respectively.

By clicking Query Editor tab we can see the sql query generated after the design. The query can
be saved at any time from the Query menu from the Menu Bar or by using CTRL-S.

User can use ALT-D and ALT-E shortcuts to move between Query Designer and Query Editor
tabs.

36
 Usage

3.7. Query Editor

If the user wants to use an extern sql query or the user knows the SQL language and wishes to
create a more complicated query , he can write directly to the query editor.

ATTENTION In this case , if the user wants to go in designer mode by clicking the Query
Designer tab , he will be notified by a message that the editor will be cleaned and the sql
entered by hand will be lost if it was not saved yet.

The query editor allows for copy, cut , paste , search and undo, redo actions. The last button from
the toolbar will run the sql. The results are visible in the table beneath the editor. If Max rows
checkbox is selected , only as many rows as entered to the text field will be shown. If 0 is entered
all the result rows will be shown. Because the process of report running can be time consuming ,
when this process starts the main window of NextReports application will be blocked , but through
a stop button the user can stop the query or the report before it finishes.

37
 Usage

Run a query with parameters

If the query contains parameters, then after the run button is pressed a new panel will be shown to
the user. Here the user can select the values from the parameters (see next image). If the parameter
is mandatory , its name will pe preceded by the character * and the report will not run until all
mandatory parameters will be selected. For a non-mandatory parameter , if no value is selected, at
runtime this value will be considered null.

Call a procedure

Inside the sql editor the user can call a stored procedure. The general syntax is like the following :

call <schema_name>.<procedure_name>(${P1}, ... , ${Pn}, ?)

where ${P1}, … , ${Pn} are procedure ‘in’ parameters. These can also be parameters defined for
the query and will appear at runtime. The ‘?’ parameter is the cursor output parameter. For Oracle
databases this is used. For other databases, the call must not contain ‘?’ parameter.

38
 Usage

If some procedure parameters are also query parameters, they may be checked as ‘stored procedure
parameters’ and a preview value must be set for them. This preview value is used inside the
procedure business to exit as fast as possible, making the column finding process as fast as
possible. For parameters that are not checked as ‘stored procedure parameters’, a default value is
used to get columns.
The user can drag and drop a procedure from the explorer panel to the query editor panel. If the
procedure is not a candidate for reporting (for example for Oracle does not have an output
parameter of type cursor) a message will notify the user. If it is a candidate, the general syntax
shown previously will be automatically written to the editor. The user will have to define the
parameters if any.
There is a general action on Procedures node in the explorer, and a particular action on every
procedure node which will validate the procedure(s), meaning will inform the user it is a candidate
for reporting.

39
 Usage

3.8. SQL Log Panel

By clicking the tab Sql Log the user can see the log generated by the NextReports application with
the information about the sql execution.
In this panel the user can look at all the accesses and queries executed in the database and can see
how long it took to execute them. For that, in the configuration file of the application the property
db.spy must be true. See NextReports Configuration Section from Chapter 4.

The current log is found on disk inside the folder log where NextReports was installed and is
called jdbc-spy.log .

SQL selects seen here and which contain parameters may not be the same with the select executed
in database, meaning that the values of the parameters are shown as strings, but they are passed
correctly with their data type to the sql.

There are two possible actions:

- Clear Log : clears log panel
- Reload Log : reloads in the log panel the last <n> lines from the log. The number of
loaded lines <n> is 100 by default . If the number is not entered or it is 0 , all the log will be
loaded.

ATTENTION The bigger the log is , the more time will be needed to load it.

40
 Usage

3.9. Status Bar

In the status bar on the left side the name of the connected data source will be printed. On the right
side the user can see the used memory <n1> / <n2> where <n1> represents how much from the
application memory is used and <n2> represents the memory that NextReports is allocated.

By mouse double-click on the memory information, a memory garbage collection will be executed
and a small report will show the memory released, the memory used and the total memory of the
application.

3.10. Report and Chart creation

A new report can be created from the current query loaded in the application from the File -> New
Report menu or from a selected query from File -> New Report From Query menu. Through these
actions the user is entering the report layout perspective. (See Layout Report Section). After
entering this perspective, the actions Save and Save As become active in the menu bar in the File
menu and in the shortcuts bar.

In the same way a new chart can be created from the current query loaded from the File -> New Chart
menu or from a selected query from File -> New Chart From Query menu. User enters the chart layout
perspective. (See Layout Chart Section).

Another way to create a report or a chart is to use the NextReports wizard.

41
 Usage

3.11. Wizard

The wizard is useful to create a report or a chart in a very short time. The wizard is accessible from
Tools -> Wizard menu or by pressing CTRL-W.

ATTENTION. If a modified and not saved query, report or chart is loaded in the application,
the user will be asked by a message to save or not the current document. If “No” is selected
the document will be lost.
The first wizard panel shows the steps that this process will follow: entity selection (report/chart),
data source selection, query creation, selection of columns visible in the report/chart , template
selection. The last step of template selection is optional and will be shown only for default report
creation. For special report types like alarms, indicators and displays another step is shown to enter
their settings.

To advance to the first step the Next button must be pressed. At any moment (step) the wizard can
be cancelled by clicking the button Cancel or we can go to the previous step, if exists, by clicking
the button Back.

42
 Usage

First step is the one of entity selection. Wizard can be used to create a report or a chart.

Also, for report, user can select the type between default, table, alarm, indicator or display.

Second step is the one of data source selection.

43
 Usage

The report / chart will be executed on this data source. The user can create a new data source
directly from this panel if the desired data source was not already created by clicking the button
(See Data Source Section).

After data source selection the user must press the button Next to advance to the next step.

In the next step the user selects some columns from a table or selects the query or writes the sql
query. For very simple reports/charts the user can just select some columns from a table. For more
advanced reports/charts if the query is known and was already created in NextReports , it can be
selected and the user can advance to the next step. If a new query must be created the user must
select the “Write sql” radio button and the editor will be made visible. The user must define also the
parameters used in the query. The parameters are specified between the following tags ${ and } .
Parameter definition is done in the parameters panel in the same manner when a query is created in
NextReports. (See Parameters Section)

For example, to use the parameter Project we must enter the expression ${Project} in the editor.

44
 Usage

To advance to the next step click Next.

Next step is different for report or chart. For report, the user selects the columns by using the
buttons and and the columns order of apparition in the report by using the buttons and .
By default all the columns from the query are selected in the order of apparition in the sql. At least
one column must be selected.

45
 Usage

For chart, the user must select the columns for X and Y axis.

46
 Usage

If there are more columns on Y axis, user can select up to five more by clicking “More Y columns”
button.

The user can click Finish to create the report / chart or can click Next to advance to the last step.

In the last step , available only for report, the user can select a template for the report by clicking
the button or selecting a template on the default templates list.
It is possible to create a new template directly from this panel by clicking the button . The new
created template will be automatically selected. (See Report Template Section)

After Finish is clicked , the user enters the report perspective or chart perspective depending the
entity selected at the beginning.

47
 Usage

If user selects a report of type alarm, last step will show all needed settings for it.

User has to choose some formatting conditions to have different backgrounds for different values.
Selected intervals must be disjunctive. For every interval, user has to also enter a message. Inside
the message user can use the actual value with $C_<column_name>. User can also select a shadow
for text.

After finish, user will see the layout explained in section 3.13. Alarms.

48
 Usage

If user selects a report of type indicator, user will be asked to enter settings like:

 Title: small text drawn on the indicator

 Description: small text shown under the current value (optional)
 Unit: value’s unit (optional)
 Min value
 Max value
 Boolean flag used to show or not min / max values
 Boolean flag used to show or not shadow for text

After finish, user will see the layout explained in section 3.14. Indicators.

49
 Usage

If user selects a report of type display, user will be asked to enter settings like:

 Title: display title

 Boolean flag used to specify if a rising value is a good thing
 Boolean flag used to show a shadow
 Different colors

After finish, user will see the layout explained in section 3.15. Displays

50
 Usage

3.12. Report Layout

Report Layout is a grid structure made of cells. A cell may be empty or may contain static text, an
application variable, an expression, a runtime parameter, an image, a hyperlink, a chart, a sql
columns or a function. A row or more successive rows of cells form a band. NextReports contains
the following types of bands:

- Page Header: Page Header rows are generated for PDF, DOCX and RTF files for every
page of the document. Also Excel files will have the content of this band seen when the
document is printed, but only if document margins are big enough.
- Header: Header rows are generated at export only once before the detail is generated.
- Detail: Detail rows are generated at export for every row of result obtained after the query
execution.
- Footer: Footer rows are generated at export only once after the detail is generated.
- Group header: Group header rows are generated at export for every group of results before
the detail is generated.
- Group footer: Group footer rows are generated at export for every group of results after the
detail is generated.

51
 Usage

- Page Footer: Page Footer rows are generated for PDF, DOCX and RTF files for every page
of the document. Also Excel files will have the content of this band seen when the
document is printed.

When a new report is created, by default it contains a header band with two rows (first one has a
static text as title, the second row contains the name of the columns from sql query), a detail band
with a row which contains the columns from sql query, and a footer band with an empty row.
For example report made on Demo data source (previous image) we can see the header band with
rows H0-H5. In this band, besides the default rows the user added some new rows which contain
some runtime parameters $P{…}. Also here there is an image $I{…} and a variable $V{DATE}
which specifies the current date when the report was exported The columns from sql query can be
seen in D0 detail band and in G1 group header band marked with $C{…}. In the group footer band
there is a function , sum of hours, for the group G1 made on the ‘Last Name’ column $F{…}. In
footer band F7 there is a variable $V{PRODUCT} which shows NextReports application version.
Any expression added to layout will be shown with $E{…} and hyperlinks will be shown with
$H{…}.

Structure panel contains a tree with four levels. On first level there is the “Report” root. On
second level we can see the bands (header, group header, detail, group footer, footer). On third
level there are the rows from every band. On the last level there are the cells from every row.

From every band node we can add with mouse right click one or more rows on the last position of
that band. Here is the only place in NextReports application where a row or more rows can be
added to an empty band.

For example, by default, when a new report is created, the footer band has no rows. Only by
selecting the footer band in the structure panel tree we can add one or more rows to it. For the
bands that already contain one or more rows, we can add new rows by using mouse right click on
the report layout panel and selecting from the popup menu Row > Insert After or Row > Insert Before
actions. The only difference between the tree action of adding rows and these actions is that here
the user can add the rows at any position inside the band, not only at the end. If the report grid is
empty, the first inserted rows will have only one column. The user can add later other columns
from the report layout panel popup menu. Any selection of a cell or a group of cells from the
structure panel tree will select the corresponding cells in the report layout panel. In the same way, a
selection of one or more cells in the report layout panel will select the corresponding cells in the
structure panel tree.

Properties Panel contains the properties of a selected cell, the common properties of a selected
group of cells, the properties of a selected row or the global properties of the report.

By selecting the “Report” node in structure panel, user can modify report global properties:
1. Type : type of report can be one of default, table, alarm, indicator or display. Table, alarm
indicator and display are special reports (with a convention based layout) that have a special
representation inside NextReports Server dashboards.
2. Paper size : paper size used by pdf, docx and rtf formats; it is also used for excel printing
3. Custom definition : this property is seen only when paper size is set to CUSTOM and it’s
elements (width, height and measure unit) are used by pdf and rtf

52
 Usage

4. Orientation : portrait or landscape, used by pdf, docx and rtf formats; it is also used for
excel printing
5. Padding : document margins in pixels used by pdf, docx, rtf and excel formats
6. Header on every page : used by pdf, docx, rtf and excel formats
7. Background image : used by pdf and html formats
8. Excel template &Excel sheet number : used by excel format to allow writing inside an
existing xls, xlsx or xlsm file in a specific sheet. This is useful if you have an excel file with
2 (or more) sheets. One sheet is the actual data sheet and the others are computations made
on values from data sheet like pivots for example. If template is of type xlsm, then the
resulted file will also have xlsm type.
9. Excel sheet name: if this property is empty, excel sheets will be named as 1,2,3,… If this
property is specified it can have one of the following:
- A static list of strings like A;B;C;D Sheets will be named in this order and if there are more
than the names in the list, the other will have the sheet number as name
- Use ${NO} as a template marker for sheet number. For example Page ${NO} will generate
sheet names as Page1, Page 2, Page 3, …
- Use ${G1} template marker for group name. In case we set ‘new page’ after group we may
want that every sheet to have the group name. If there are more sheets than groups, the other
will have the sheet number as name

Report properties can also be shown if user selects layout’s upper left corner.

ATTENTION. When a background image is set all background colors for cells are ignored.

Also, in properties panel user can edit the cell text , can select a font, a background and foreground
color, the horizontal and vertical text alignment, a pattern (for example a date pattern), padding,
border, wrap text, hide repeated value, hide when expression and formatting conditions. The cell
content can be modified also from the report layout panel by mouse double-clicking on the cell.

ATTENTION. A note has to be made about selecting colors for excel export. Excel has 56
recognizable colors. So if you want your colors to be the same with those selected, you can
select them inside color chooser from “Excel Palette” tab. If your colors are not Excel
recognizable, the result may not be the one you wanted.

If in next-reports.properties configuration file accessibility.html is set to true another three

accessibility properties used for html can be seen: headers, id , scope. (see Configuration section
from Advanced Topics chapter).

53
 Usage

Almost all properties are self-explanatory. Some of them have no importance for a specific export
format (like foreground for TXT export). Just a few words to add about last three of them: ‘hide
repeated value’, ‘hide when expression’ and ‘formatting conditions’.

‘Hide repeated value’ property is used when we do not want to show the same value (in the same
column) of a cell in all the following records.

‘Hide when expression’ property is a string expression. If expression is evaluated as true, the
corresponding rendered cell will be empty. If all cells from a row have such expressions, and all
expressions are evaluated as true, that row will not be rendered at all. This is useful in case you
want to show cell content only when an expression is true. Also you can create layout expressions
which you do not want to see rendered but which you want to use in some functions.

‘Formatting conditions’ are used if the user wants to modify general properties of a cell with the
values set if some conditions are met. A formatting condition has an expression which will be
evaluated for every value of the cell, a property to overwrite and the property value to overwrite
with. User can select between “Current value”, meaning the value of the selected cell will be
compared, and “Other value”, meaning that an arbitrary value from a desired expression will be
compared.

54
 Usage

When user adds or edits a formatting condition, he will select an operator and a value (or two
values). The expression is “${val} <operator> <value> <value2>” which means the current value
will be compared with the value entered by user, or if operator is ‘[]’ the current value will be
checked to be inside the interval [value, value2]. User can select one of the following properties:
foreground, background, font and border. Any property has its own value chooser used when the
property value is selected.

Row properties are shown if user clicks on a row header inside layout or on the corresponding
node in the explorer tree.

55
 Usage

‘New page’ property specifies that exported row from that band will always start on a new page.
This property has meaning for PDF, DOCX, RTF and EXCEL exporter types. To see in layout that
a row starts on a new page, the row icon will have a small ‘+’ bullet :

‘Formatting conditions’ property is similar to the one on a cell. The only difference is that user
must create an expression which is used as left operand for conditions:

User can create a new expression using button, or he can select an already defined expression
using button.

56
 Usage

Layout Panel contains the bands, the rows and the cells. On mouse right click a popup menu is
shown. From this popup we can execute operations on cells. A user can edit cell content also by
selecting the cell and pressing enter key. Pressing again enter will validate the content and the user
will exit edit mode. Pressing escape will cancel the edit mode. User can move between cells with
the arrow keys.

The following actions can be done:

- Copy : select cell or a group of cells for copy (CTRL-C)

- Cut : delete cell or a group of cells for copy (CTRL-X)
- Paste : copy the cell or a group of cells (CTRL-V)
- Insert > Text : insert static text
- Insert > Variable : insert variable. NextReports has the following internal variables:
DATE : runtime current date
ROW : row number in the result obtained after the sql query execution
GROUP_ROW : row number in the current group. If there is no group defined inside the
report, this is the same with ROW variable
USER : system current user
PRODUCT : current NextReports version
REPORT_NAME : report name
PAGE_NO : current page number (for PDF, DOCX, RTF and EXCEL documents)
TOTAL_PAGE_NO : total number of pages for PDF document

ATTENTION TOTAL_PAGE_NO cannot be used inside expressions because it is

evaluated when the document is closed. To have something like “Page 1 of 10” in your
header or footer, you have to create two cells, first is an expression “Page “ +
$V_PAGE_NO + “ of”, second is the TOTAL_PAGE_NO variable.

57
 Usage

- Insert > Sql Column : insert a new column from query (it is possible in the detail band and in
the group bands)

- Insert > Expression : insert an expression.

58
 Usage

An expression can be created from sql columns, variables, parameters, functions, operators
and literals. With a mouse double-click on any of them, the selection will be added to the
editor at the current caret position.

ATTENTION If the selected cell is not in detail or group bands, sql columns are not
shown inside expression editor, because they cannot be evaluated. Also, functions are
shown only in footer bands.

Expression must have a unique name inside a report.

Expression result type can be numeric ( like $C_Hours * 60 ), string ( like $C_Last_Name
+ " " + $C_First_Name ), date. Some operators can be written in two modes, for example
‘/’ and ‘div’ are the same division operator. (see the list of operators from expression
editor).
‘if..else’ has a special syntax (see example below) :

if ( $C_Hours < 6) { y=6; }

else { y= $C_Hours ; }

59
 Usage

If we want a double result, we should use java doubleValue() method like in the following
example:

$C_Hours.doubleValue() / 100

If a function is used inside an expression, we do not have to convert to double because any
function is computed as a double value.

- : insert a function (this is possible inside report footer band, inside group
Insert > Function
footer bands, inside report header band, inside group header bands)

60
 Usage

A function can be created for a column or for an expression. If no expression is used inside
a report, only the column selection will be shown.

- Insert > Parameter : insert a runtime parameter from the ones defined

- Insert > Image :insert an image from a file. To resize the image, user has to select the image
cell, then press mouse right button and select “Resize Image” action from the popup menu.

User can select width and height in pixels (actual size can be seen on the right) or a scale
percent. If “Keep aspect ratio” is selected, by modifying one of width or height, the other
will be automatically updated.

ATTENTION. Image size does not depend of column size. That means even if we select
a column size, until we resize the image, the image will still have its original size.

- Insert > Image Sql Column : insert a new image column from query (it is possible in the detail
band and in the group bands). Image column must be a blob or other image type for
different databases. (for example MS SQL has image and varbinary types). User can set
width and height similar as with a simple Image element.

ATTENTION. Image must be of type png, gif or jpeg.

- Insert > Barcode :

insert a barcode. User can select a barcode type and a value entered by
hand or taken from a database column.

61
 Usage

Generated barcode is an image and can be resized like any image using “Resize Image” action
from the popup menu.

- Insert > Hyperlink : insert a hyperlink (text and url)

- Insert > Chart :

insert a chart created with NextReports. Because chart is created as an image
after export, chart can be resized like any image using “Resize Image” action from the
popup menu (as shown previously)

ATTENTION. If your chart has parameters, they have default values and those values
will be used at runtime unless you define the same parameters (name, type, selection)
also inside the report. In that case, the parameter values passed to the report will be
also used for the chart.

- Extract Chart :
extract a chart from a report to a local chart file (under Charts folder for the
same data source)

- Edit Chart : if a cell contains a chart, this chart can be edited. The child chart will be opened:

The main toolbar will have “Return to Parent Report” action enabled which will also
contain the name of the parent report. After the chart is edited, when user clicks “Return to
Parent Report” the saved chart will also be saved inside the parent report.

ATTENTION. You should click “return” in order to save the edited chart inside
parent report.

- Insert > Report :

insert a report created with NextReports. A report can be inserted in any cell
from header, group, detail, footer. If a report is inserted inside detail band and it has
parameters, those parameters are automatically linked with columns from parent report.

62
 Usage

Parameter’s name must be identical with the alias of the column from parent report,
so that the value is passed to the parameter.

ATTENTION. Depending on your desired exported format, using reports inside

another report may show you a different exported file.

- Extract Report :
extract a report from a report to a local report file (under Reports folder for
the same data source)

- Edit Report : if
a cell contains a report, this report can be edited. The child report will be
opened. The main toolbar will have “Return to Parent Report” action enabled which will
also contain the name of the parent report. After the report is edited, when user clicks
“Return to Parent Report” the saved child report will also be saved inside the parent report.
A child report can also contain another child report. By using “Edit Report” and “Return to
Parent Report” actions user can navigate inside and outside reports.

ATTENTION. You should click “return” in order to save the edited child report
inside parent report.

- Insert > Multiple Report :

insert a report as a FOR element which has a special property called
“multiple report sql”. This sql will return values for a specific column. At runtime, FOR
element will be replaced with as many report elements as many values are returned from
sql. Every such report element will be passed the corresponding value to be used by internal
parameters.

ATTENTION. Report must contain a parameter with the same name as the column
name from “multiple report sql”. Users can use only one “Multiple Report” element
inside a layout.

This element can be used if you want to scale your data horizontally and your report has a
common part which can be defined as a separated report with at least one business
parameter.

63
 Usage

- : clear the content of a cell (make it empty) or a group of cells. This can also be
Delete cell
done with DELETE on selected cells.

- Group > Add : add a new group .

The user must select the column on which the group is made and optionally a function, the
column on which the function is computed and if the group has or not a row inside the
header band. Also if you want a new page to be created after this group (for pdf, docx and
rtf) or a new sheet to be added after this group (excel) you will just have to select “New
Page After” property.

One of the following functions can be added :

Sum : sum of elements from the column group

Min : minimum element from the column group
Max : maximum element from the column group
Average : average of elements from the column group
Count : number of elements from the column group
Count Distinct : distinct number of elements from the column group

If more groups are added, their order is given from first to last. For example for groups G1,
G2 and G3 added in this order , the bands will be like this:
G1 header
G2 header
G3 header
Detail
G3 footer
G2 footer
G1 footer
For every group band (header or footer) the user can see a tooltip with the name of the
column on which the group is made when moving the mouse on the left of the report layout
panel.

- Group > Remove : remove group

- Group > Modify :modify group. The column on which the group is made and the “New Page
After” option can be modified.

64
 Usage

- Merge Cells: merge two or more cells. The cells must form a matrix and only one cell can
not be empty.
- Unmerge cells : A cell obtained by a merge action can be unmerged to its entities.

- Delete all : The entire report panel layout will be cleared.

On any column header using the mouse right button the following actions can be done :

- Insert column before : insert a column before the selected one

- Insert column after : insert a column after the selected one
- Remove column : remove the selected column (can be done on single or on multiple
selection)
- Size (pixels) : set the size of the selected column in pixels (this action is visible only if the
width button is pressed and can be done on single or on multiple selection)
- Size (characters) : similar with Size (pixels) action and useful for exporting to a flat file text
format

On any row header using the mouse right button the following actions can be done:

- Insert row before : insert a row before the selected one

- Insert row after : insert a row after the selected one
- Remove row : remove the selected row

Menu Bar from layout panel contains the export actions:

- HTML
- EXCEL (xls)
- EXCEL (xlsx)
- PDF
- DOCX
- RTF
- XML
- CSV (comma-separated values)

65
 Usage

- TSV (tab-separated values)

- TXT (flat text file with fixed character widths for columns)

First action allows the user to set the width of the columns. Without the selection, all the widths
are automatically generated to fit. After selecting this toggle button the user can select the size of a
column by right-clicking on the column header and the size of all selected columns can be
modified. Also, the user can drag with the mouse the column separator to modify the size of the
column from its left. The size cannot be less than 10 pixels or greater than 1500 pixels.
A ruler can be seen if ‘Show ruler’ property is checked in the settings. The ruler unit can be
centimeter or inch and is set also in the settings. Also with a double click on ruler, the unit is
automatically inversed.
Here are found also the buttons for copying the cell properties (except the content and pattern) to
another cell or group of cells. The user selects a cell and presses the button . Then the user selects
another cell or group of cells and presses the button .

Report Layout also has the options to undo or redo the actions you made.
The option allows to apply a report template to the current layout.
The option allows to save the template of the current report layout.

If ‘Records’ is checked the report will generate only the first number of records specified. This is
useful if you want to see how the report looks (like a preview). The user can also modify the data
source on which the report is run. By default the data source on which the report was created is
selected. But if you know you have another database with the same structure, you can select it and
run the report. This is useful for the case in which two or more similar databases exist (like
databases for test and production).

For all the exporters the user is prompted a runtime panel to select the parameters value only if such
parameters where defined.

After the report is generated, it will be automatically opened with the default application for that
kind of file installed in the system.

The cells can be selected with the mouse or with the keyboard’s keys. There are three selection
types with the mouse:
- Discontinuous selection: select a cell with the mouse and then to add to the selection any
other cell keep the CTRL key pressed.
- Continuous selection: select a cell with the mouse and then to select all the cells between
this cell and another cell, keep the SHIFT key pressed.
- Continuous selection through drag&drop : select a cell with the mouse and then keep the
mouse pressed and drag it to select all the cells you want

After selecting a cell, keeping the SHIFT key pressed and using the arrow keys will allow of a
continuous cell selection.

66
 Usage

Report layout supports a zoom operation from the spinner inside the toolbar. Layout can be zoomed
between 50% and 300%. The same operation can be achieved using CTRL pressed with the mouse
wheel.

Previous image shows the report from Demo data source exported to PDF.

67
 Usage

3.13. Alarm Reports

“Alarms” are special types of reports that can be published to a NextReports Server. Inside designer
they must have three cells in the detail band :

 first is a number column (status) with formatting conditions for background color
 second is an expression "if .. else .." which returns a different message for every known
status (number column value)
 third is a Boolean value to specify if message will have a shadow or not (this is optional)

On the server, first cell is drawn as a status led which will have the color the same with cell
background color. The message will be shown next to the image.

For example, the formatting conditions for the first cell can be:

This image shows that for a value < 50 , background color is red, for value between 51 and 100
value is yellow and for value >= 101 background color is blue.

Expression in the second cell is defined as:

68
 Usage

if ( $C_HOURSNO < 50) {

"Project delay is imminent! (Only " + $C_HOURSNO + " hours worked)" }
else {
if ( $C_HOURSNO < 101) {
"Project delay is possible. (" + $C_HOURSNO + " hours worked)" }
else {
"Project is on target. (" + $C_HOURSNO + " hours worked)"
}
}

On the server, the result will be like this:

ATTENTION To see the report as an alarm inside server, be sure that your report has the
type ‘alarm’ selected.

69
 Usage

3.14. Indicator Reports

“Indicators” are special types of reports that can be published to a NextReports Server. Inside
designer they must have a layout like:

First header row H0 contains four cells:

 Title indicator
 Description (optional)
 Unit (optional)
 Shadow for text (optional)

Second header row H1 contains also three cells, but all of them are mandatory:
 Minimum value
 Maximum value
 A Boolean flag : true means minimum and maximum values will be shown on the server
representation

Detail row D0 contains a single mandatory cell which must be a column or an expression. This cell
has two important properties which are used by server representation: foreground and background.

A server representation will look like the following:

Minimum value, maximum value and actual value are all appended with the unit if that is specified
inside report layout. Description (if any) is shown under the current value.

ATTENTION To see the report as an indicator inside server, be sure that your report has the
type ‘indicator’ selected.

70
 Usage

3.15. Display Reports

“Displays” are special types of reports that can be published to a NextReports Server.

"Display" shows a value (without min/max boundaries like those used for Indicator) which is
associated with a period of time. You can think as example for: Number of site visitors per day,
Interest Rate per month, Profit per year. Also, this widget has the possibility to show how this value
performed regarding a previous value (on previous period of time).

Inside designer they must have a layout like the following:

Header row contains three cells:

 Title of display report, which may contain or not a parameter. Title may be empty.
 A Boolean value (shouldRise) which specifies if a rise (true) or a decrease(false) is a good
thing
 A Boolean value (shadow) which specifies if a shadow is visible (true) or not (false)

Detail row has mandatory only the first cell. If second cell is entered, then all the cells must be
entered. These cells represent:
 The value that is shown by the display
 Previous value of the display (on previous time period)
 Expression (up) which computes a Boolean value to show if the value is bigger (true) or less
(false) than previous one: $C_value >= $C_prev. If this expression is true an up arrow will
be shown, otherwise a down arrow will be shown. The color of the arrow is green if the
evolution is in the good direction (up=true & shouldRise=true, or up=false &
shouldRise=false) or red otherwise.
 Expression which computes the percent which the actual value increased or decreased in
comparison with previous value:
if ( ($C_value == 0) || ($C_prev == 0) || ($C_value == null) || ($C_prev == null)) {
0;
} else if ( $C_value >= $C_prev ) {
( $C_value - $C_prev ) *100 / $C_value.doubleValue();
} else {
( $C_prev - $C_value ) *100 / $C_prev.doubleValue();
}

Foreground properties for title, $C{value} and $C{prev} cells specify the colors used to draw the
strings. Background property for title cell specifies the background of display widget.

A server representation will look like the following:

71
 Usage

ATTENTION To see the report as a display widget inside server, be sure that your report has
the type ‘display’ selected.

72
 Usage

3.16. Report Templates

Report templates are files which keep the properties for some report layout cells. By default, the
report created with the wizard contains a header band with two rows : a title and a header of the
column names from sql query; a detail band with a column row and a footer band with an empty
row. A template contains the properties for those four default rows created: title , column header,
column detail and footer . Such a template is useful when the user wants to make the report
creation an easier process.

A template can be created from Tools > Create Template menu. For every row the user selects the
desired properties and then saves the template to file on disk.
A template can be modified from Tools > Modify Template menu.

A template can be applied from Tools > Apply Template menu to any loaded report. Only the
corresponding template rows from report will be modified. The others, if any, will remain
unchanged.

A template can be saved (created) from Tools > ExtractTemplate menu. The template of the current
loaded report will be saved to a specified file.

73
 Usage

3.17. Chart Layout

When a chart is created or opened, user is redirected to chart perspective where the chart layout is
present. Chart layout consists of four components (title, main, xAxis, and yAxis) which can be
selected with the mouse. Every component has a list of properties.
For yAxis, user can select a function. This means that data will be grouped after xAxis and that the
function will be performed for all the data in every group. If y column is not of number type, the
function is mandatory and can be one of COUNT or COUNT DISTINCT. If more columns are
selected on Y axis and if a numeric function is selected, all the columns must be of number type.
ATTENTION. The query must be ordered first by selected xAxis Column because the query
is not modified in the layout (by selecting different x columns). If ‘order by’ x column is not
presented in the query, the computed functions will not be the desired ones.

Main component is represented by the image seen in the layout. By selecting it, the properties for
it will bee seen on the left. User can select the following:
- type of the chart : bar, bar line, horizontal bar, stacked bar, stacked bar line, horizontal
stacked bar, pie, line, area or bubble. When create a new chart, default type is bar.

74
 Usage

For ‘bar line’ and ‘stacked bar line’ there is a convention that the last series (column) is of
type line, as opposite to all other series which are of type bar / stacked bar.
For ‘bubble’ there is a convention on how to select the columns. Bubble charts should have
exactly 5 columns: a string ID column (labels for bubbles), a string SERIES column
(indicates which series does a bubble belong) and three columns which represent the values
on X, Y and Z axis. The values from Z column are used to compute the radius of bubbles.
The convention used by designer is to select ID column for layout x column and X, Y, Z,
SERIES columns for layout y columns, exactly in this order.
- background color of the chart
- chart’s color . For pie chart type there are another nine properties named color2, color3, …
color10 for next slices colors. These colors are also used if there are more Y columns or if
the chart type is stacked bar.
- chart style : depends of chart type (for bar as example we can select cylinder, parallelepiped
and so on)
- tooltip message : this is the tooltip message used by HTML5 charts; if not entered a default
will be used (it has no meaning for flash charts)

There are some markups that can be used inside the text:
#val represents the actual Y value
#x represents the actual X label value
#total represents the sum of all y values; it has meaning for stacked bar, horizontal stacked
bar and pie charts
#percent represents the percent of actual Y value from total; it has meaning for pie chart
<br> can be used to have a new line inside tooltip
#z represents the actual Z value; it has meaning for bubble chart
#c represents the actual SERIES value (category); it has meaning for bubble chart
#label represents the actual ID value; it has meaning for bubble chart

75
 Usage

Default values used are:

#val for all simple charts
#val / #total for stacked bars and horizontal stacked bars chart
#val / #total<br>#percent% of 100% for pie chart
#label<br>X: #x<br>Y: #val<br>Z: #z<br>Series: #c for bubble chart
- transparency property selects how transparent the chart is
- font : only font size is considered for main text (for example text shown in pie chart’s slices)

X Axis component has the following properties:

- column : chart column for x axis : can also be selected from layout from the combo
- show label : specifies if the labels on X axis will be visible or not
- show label font: font used by X axis labels
- label color : labels color on X axis
- orientation : label text orientation
- pattern : label pattern
- show grid : specifies if grid lines on X axis are visible or not
- grid color : color for grid lines on X axis
- legend : X axis legend which has a text, a font and a color
- color of the X axis itself
Y Axis Component has the following properties:
- column: chart column for y axis : can also be selected from layout from the combo. All the
columns that are not of Number type are represented with a gray color. When selecting such
a column, the layout automatically selects COUNT function, and only this and COUNT
DISTINCT functions can be selected.

76
 Usage

- column 2 to 10 : represent other columns that can be added on Y axis. User can select them
in order (you cannot select column 3 for example, if you did not select column 2). For pie
chart even if more Y columns are selected only the first is taken into account.
- column legend : these properties will show a legend for the corresponding selected column
- column query : if it is desired to have dynamic columns, this query must return {column,
column legend} string pairs. In this case there is no need to enter any static column and
column legend. Your query behind must be also dynamically created.
- show label : specifies if Y axis labels are visible or not
- show label font : font used by Y axis labels

- label color : labels color for Y axis

- show grid : specifies if grid lines for Y axis are visible or not
- grid color : color for grid lines on Y axis

77
 Usage

- legend : Y axis legend which has a text, a font and a color

- pattern : this property changes the pattern used to show values on tooltips for html5 / flash
charts or on the graphics for image export if ‘show values’ is selected
- show values : this property is used only for image export to show y values over image (for
html5 / flash export values are always seen as tooltips)
- color of the y axis itself
- show dual axis : if chart contain 2 or more series for comparison sometimes data can differ
as order of magnitude and there are needed different Y axis to be able to see all series in a
nice form. By selecting this property, chart is instructed to draw a second Y axis
- dual axis legend : Y second axis legend which has a text, a font and a color
- series number : this specifies how many series will be represented on Y second axis. By
default, if nothing is specified, only the last series will be represented on Y second axis.
- starting from zero : this will make min value to be zero only if computed min value is
bigger than zero
ATTENTION Y second axis has meaning for charts of type line, simple bar and combo bar-
line. To make your charts look good you must have charts on Y axis with similar order of
magnitude and the same is valid for second Y axis. Dual Axis feature is used only by HTML5
exporter.
Title Component has the following properties: text, font, foreground color and horizontal
alignment.

When a new chart is created, only x and y axis columns are mandatory. All the other properties are
optional.
ATTENTION If horizontal bar or horizontal stacked bar type is selected, X and Y axis are
reversed in the layout perspective.
It is possible to view parameters values inside title or legends text. For that the text must contain the
parameter: $P{<parameter_name>} .

To preview the chart as HTML5, user selects the button from the layout toolbar. This preview
is useful if we want to publish the chart to a web server. The preview process will run the query and
if data exists, the browser will be opened with a HTML5 chart object. With mouse right click the
chart can be saved locally as an image.

To preview the chart as a flash, user selects the button from the layout toolbar. This preview is
also useful if we want to publish the chart to a web server. The preview process will run the query

78
 Usage

and if data exists, the browser will be opened with a flash chart object. With mouse right click the
chart can be saved locally as an image.
ATTENTION Flash should be used only if there are some restrictions to server browser
clients so that they do not support HTML5, otherwise you should use HTML5 because it is
widely supported also from Android devices.
The first HTML5 / flash preview process will start a local small server and NextReports uses a web
port chart.webserver.port which can be modified in Settings action to allow for chart
visualization. This server allows only for connections from the current machine.

To preview the chart as an image, user selects the button from the layout toolbar. This preview
is useful if we want to insert the chart inside a report. Result image is created inside “reports” folder
and it is shown inside an application dialog.
A very useful feature, if you have more charts to design with same colors, is to save a chart
template and then to use it on any other chart. By using the button , all color properties from a
chart (background, foregrounds, title color, axis colors, grid colors, label colors and so on) will be
saved to a special chart template. To use a saved template you have to use the button .
First combo in toolbar allows selecting for another data source to preview the chart. By default the
current data source is selected. Inside combo, all data sources with the same driver are found. If you
have two data sources with the same structure it is very easy to change between them.

79
 Usage

3.18. Publish & Download

NextReports application allows for report or chart publishing on a NextReports server and for
report or chart downloading from server. A NextReports server is a web application which manages
data sources, reports and charts, schedules reports to run at specific moments in time and allows for
charts and special kind of reports to be viewed in real time.

To publish a report / chart the user must know a NextReports server (url) and must have a valid
account on that server (user and password).

After pressing Next button the user is authenticated on the server. If the authentication succeeds, the
user will be allowed to publish the report / chart.

80
 Usage

The user has to select the path on the server where he wants to publish the report / chart. The user is
allowed to create folders on the server. Also, if the data source is not already on the server, the user
can publish the current report / chart data source.

If the selected report / chart was previously published, the form will be completed by default with
name, server path and data source.

ATTENTION Even if report has ‘table’ type , if no default values for parameters are
selected or if the report has no header band , the report will not be shown on server in the list
of candidates to be added to dashboards.

In the same manner, if the report has ‘alarm’, ‘indicator’ or ‘display’ type, if no default
values for parameters are selected, the report will not be shown on server in the list of alarm,
indicator or display candidates.

If an alarm report does not have the needed structure, on the server the led will have a white
color, same as if no data was found.

After pressing Finish, the action is started and the user will be notified by a message if the publish
succeeded or if an error occurred.

To download a report / chart (or more) from a server the user will have to authenticate and after that
he will select the report / chart he wants. The selected report / chart will be downloaded to
NextReports designer application for the current connected data source.

If “Reports” or “Charts” node is selected, Publish action from their menu will allow making a bulk
publish of more reports simultaneously:

ATTENTION When doing a bulk publish, you must know that all your selected reports are
created for the same data source

81
 4
Chapter

4. Advanced Topics
4.1. Internal Structure

The folder where NextReports application was installed contains the following files and folders:

+ config : the folder where the configuration files are founfd

log4j.properties : here the logs used by NextReports are defined
next-reports.properties : this is the configuration file of NextReports application
+ demo : this folder contains the Demo Derby database
+ jdbc-drivers : in this folder there are the drivers for databases (Derby, Mysql, Oracle,
MSSQL Server, Firebird)
+ jre : this folder contains the installed java runtime environment (jre) , if the user choosed an
installation file with jre.
+ lib : this folder contains the jars used by NextReports application
+ logs : in this folder the logs generated by NextReports can be found (.log files)
+ output : here there is a folder structure , every folder has a name of a data source from
NextReports. Under any of such folder all the queries and reports for that data source are
saved. (.report, .query files).
+ reports : this is the place where ale exported reports and chart images will be saved (.pdf,
.html, … files)
+ templates : in this folder there are the report templates (.ntempl files)
+ chart-webroot : contains the files needed to preview NextReports charts

- datasource.xml : in this file all data sources created in NextReports are saved
- schemas.xml : in this file the application saves the visible schemas selected by the user for
every data source
- nextreports.vmoptions : in this file there are specified the virtual machine options. By
default the maximum memory for NextReports is 256m (-Xmx256m). If you know you
need more memory you can add a minimum value (-Xms128m for example) and you can
modify the maximum memory.

ATTENTION You must not delete files or folders from NextReports internal structure.
The only files that can be deleted with no impact on the application are the reports files generated
in the folder reports.

82
 Advanced Topics

4.2. Configuration

NextReports application allows configuring some internal properties. This configuration can be
done inside the file next-reports.properties from config folder where NextReports was installed.
Also the most important properties can be modified through the Settings menu from application.

ATTENTION If any of internal properties is modified in configuration file, NextReports

application must be restarted to take into account the new values.

db.spy=true

For true value, inside the log file the user can see all the queries to the databases. If this value is
set to false nothing will be written inside the log. This log can be seen from NextReports. (See
SQL Log Panel Section)

singlesource.autoconnect=true

The value true means that if only one data source is created inside NextReports, at application
startup that data source will be automatically connect without selecting from the popup menu
the Connect option. If this is not to be desired, we must set the value to false.

console.redirect=false
console.file=./log/console.log

By default console messages are not visible in the log. If the user wants to see them, he has to
set the value true for console.redirect. The file where those messages will be logged is
specified by the console.file property.

connection.timeout=5

When we try to connect to a database, if this time of seconds elapsed the connection is aborted
with a TimeoutException. By default this value is set to 5 seconds.

query.timeout=240

The execution of every sql query is stopped if more than query.timeout seconds elapsed. This
value is specified in seconds. By default the value is set to 240 seconds.

font.directories=C:\\WINDOWS\\Fonts

NextReports tries to find the system registered fonts in some default locations. For Windows it
will look in the Fonts directory of Windows installation folder, and for Linux it will look in
‘/usr/X11R6/lib/X11/fonts’ and ‘/usr/share/fonts’ folders.If the fonts are not found , the pdf

83
 Advanced Topics

export will have “Times New Roman” font discarding all property fonts. To add other known
font locations you can specify their path here , separated by comma.

nextreports.pdf.encoding=Cp1250
nextreports.pdf.font=C:\\Windows\\Fonts\\Times.ttf

If the database contains other characters than latin characters (for example greek characters) the
pdf report cannot be correctly exported unless the character set is specified here. By default no
character set is entered.

One of the following character sets can be entered:

Cp1250 - Eastern/Central Europe

Cp1252 - Latin 1 (WINANSI)
Cp1257 - Baltic
MacRoman - for Mac OS

Cp1251 - Cyrillic
Cp1253 - Greek
Cp1254 - Turkish
Cp1255 - Hebrew
Cp1256 - Arabic
Cp1258 - Vietnam
Cp874 - Thai

Identity-H - The Unicode encoding with horizontal writing

Identity-V - The Unicode encoding with vertical writing

ATTENTION If a character set is specified, also the full path to a system font must be
declared. The exported pdf report will use this font for data generation and will ignore any
font selected in the cell report layout properties!

nextreports.pdf.direction=0

If report contains text that must be shown right-to-left then this property must be used with
value 3. Other values can be 0 for default, 1 for non bidirectional text and 2 for left-to-right
text.

nextreports.pdf.arabicOptions=0

This property is in relation with shape of arabic characters. It can have following values : 0 for
nothing, 1 to eliminate arabic vowels, 4 to compose the tashkeel in the ligatures, 8 to do some
extra ligatures.

84
 Advanced Topics

accessibility.html=true

If this property is set to true , the headers, id and scope html accessibility properties can be set
for every cell in the report layout properties panel. These properties are used by screen readers
applications and they have meaning only for html. By default, this property is set to false.

oracle.net.tns_admin=D:\oracle\product\10.2.0\db_1\NETWORK\ADMIN

This property specify the path to the Oracle client installed on the computer where NextReports
is also installed. If this property is set , the user can create an Oracle data source just specifying
the database name from the tnsnames.ora file selecting from driver template “Oracle – Tns
Name” type.

A4.warning=true

If this property is set to true, after a column Size action in report layout, if the total column
widths is bigger than A4 dimension, user will be notified by a message.

max.rows.checked=true

If this property is set to true then, by default, max rows check box from sql builder run panel
will be selected, otherwise will not be selected.

csv.delimiter=,

By default, a comma is used as csv delimiter. Csv delimiter must be a character; it cannot be a
quote character or an end line.

ruler.isVisible=true

If this property is set to true, a ruler is shown in report layout panel when the custom size is
used.

ruler.unit=cm

Ruler unit may be cm (centimeter), or in (inch). This property is used if ruler is visible.

chart.webserver.port=8083

Port for the web server used to preview charts

85
 Advanced Topics

locale=

This property is used to format date, time, numbers. Default (if nothing entered) is the locale of
your machine. The string contains <language>,<country> . For example locale=en,GB for
English, United Kingdom. For a list of supported locales in java see
http://www.oracle.com/technetwork/java/javase/locales-137662.html

86
 Advanced Topics

4.3. Adding support for your language

If you want to internationalize NextReports Designer for your language, you can do it by yourself.

Inside <installation folder>/lib folder inside nextreports-designer-6.0.jar you can find an i18n
folder with current supported languages.

Take one of the files and create a new one with the name like:

next-ui_<language>_<country>.properties

You can find all the language and country codes here:
http://www.oracle.com/technetwork/java/javase/locales-137662.html . For example for Spanish the
name will be: next-ui_es_ES.properties

Put this file inside jar along with others i18n files.

Although, all i18n files from jar must contain a new property:

language.<language>_<country>=<name of the language>

For example, for Spanish you will add property language.es_ES to all files.

If we want to show the flag of the country in menu bar action you have to put png flag image in jar
in images folder and in images.properties file put a new entry:

flag-<language>_<country>=<image_name>.png

87
 Annex

4.4. Adding support for other JDBC driver

NextReports allows users to add their own JDBC drivers. We are using Vertica JDBC driver here
as example. From version 6.2 Vertica driver is added by default.

Such process can be resumed by following steps:

1. JDBC jar driver is added inside jdbc-drivers folder

2. Driver must be added in driver_templates.xml which can be found inside designer in

installation folder in \lib\nextreports-designer-6.2.jar :
<driver>
<type>Vertica</type>
<classname>com.vertica.jdbc.Driver</classname>
<urltemplate>jdbc:vertica://<server>:<port>/<database></urltemplate>
<defaultport>5433</defaultport>
</driver>

3. You need to create a Dialect class for that type of driver. This dialect does a mapping
between database types and java sql types and has some utilities methods.

import java.sql.Types;
import ro.nextreports.engine.util.ProcUtil;

public class VerticaDialect extends AbstractDialect {

public VerticaDialect() {

super();
registerColumnType("binary", Types.BLOB);
registerColumnType("varbinary", Types.BLOB);
registerColumnType("bytea", Types.BLOB);
registerColumnType("raw", Types.BLOB);
registerColumnType("boolean", Types.BOOLEAN);
registerColumnType("char", Types.CHAR);
registerColumnType("varchar", Types.VARCHAR);
registerColumnType("date", Types.DATE);
registerColumnType("timestamp", Types.TIMESTAMP);
registerColumnType("timestamp with timezone", Types.TIMESTAMP);
registerColumnType("datetime", Types.TIMESTAMP);
registerColumnType("smalldatetime", Types.TIMESTAMP);
registerColumnType("double precision", Types.DOUBLE);
registerColumnType("float", Types.FLOAT);
registerColumnType("float8", Types.FLOAT);
registerColumnType("real", Types.DOUBLE);
registerColumnType("bigint", Types.BIGINT);
registerColumnType("smallint", Types.SMALLINT);
registerColumnType("integer", Types.INTEGER);

88
 Annex

registerColumnType("int", Types.INTEGER);
registerColumnType("tinyint", Types.INTEGER);
registerColumnType("int8", Types.INTEGER);
registerColumnType("decimal", Types.INTEGER);
registerColumnType("numeric", Types.NUMERIC);
registerColumnType("number", Types.NUMERIC);
registerColumnType("money", Types.NUMERIC);
registerColumnType("time", Types.TIME);
registerColumnType("time with timezone", Types.TIME);
registerColumnType("interval", Types.TIME);
}

public String getCurrentDate() throws DialectException {

return "current_date";
}

public String getCurrentTimestamp() throws DialectException {

return "current_timestamp";
}

public String getCurrentTime() throws DialectException {

return "current_time";
}

public String getCurrentDateSelect() {

return "select current_date";
}

public String getRecycleBinTablePrefix() {

return null;
}

public String getCursorSqlTypeName() {

return ProcUtil.REF_CURSOR;
}

public int getCursorSqlType() {

return Types.OTHER;
}

public String getSqlChecker() {

return "select 1";
}
}

89
 Annex

4. You must register the dialect in NextReports. To make this happen in designer you have to
add some java VM parameters (for native installers you add them inside
nextreports.vmoptions file; for zip distribution you add them in run file):

-Dnext.dialect.database_1="Vertica Database"
-Dnext.dialect.class_1="mypackage.VerticaDialect".

ATTENTION First parameter must be the name taken from DataBaseMetaData

.getDatabaseProductName().

If you need to register more dialects, you use different suffix indexes.

90
 Annex

4.5. Annex

Menu

ALT-F : open File menu

ALT-P : open Perspective menu
ALT-T : open Tools menu
ALT-H : open Help menu
ALT-L : open Language menu

Actions

CTRL-S : save current file (query / report / chart)

CTRL-D : add data source
CTRL-Q : new query
CTRL-O : open query
CTRL-R : new report
CTRL-P : open report
CTRL-H : new chart
CTRL-A : open chart
CTRL-U : publish report / chart
CTRL-W : wizard
CTRL-I : internationalization of report / chart
CTRL-L : restore layout
CTRL-1 : open query perspective
CTRL-2 : open layout perspective
CTRL-4 : run query
CTRL-SHIFT-A : apply report template
CTRL-BACKSPACE : return to parent report
F1 : tutorial
F2 : manual
F3 : quick start

Layout

CTRL-C : select cells for copy

CTRL-X : cut cells
CTRL-V : copy cells
DELETE : delete cells
CTRL-Z : undo
CTRL-Y : redo
ENTER : edit selected cell
ESCAPE : stop edit selected cell

91
 Annex

Arrow keys : move selection

CTRL+mouse : discontinuous selection of cells
SHIFT+mouse : continuous selection of cells (matrix) between the initial selected cell and the cell
selected after keeping pressed SHIFT
mouse drag : continuous selection of cells

Parameters Table

ENTER : edit selected parameter

INSERT : add parameter
DELETE : delete selected parameters

92