ADVANTAGE SOFTWARE FACTORY NextReports

User Guide Version 7.0

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 .....................................................................................................................14 3.3. Object Explorer Panel .......................................................................................................15 3.4. Data Sources .....................................................................................................................20 3.5. Parameters .........................................................................................................................24

3.5.1. Create a new parameter ............................................................................................... 24 3.5.2. Add an existing parameter .......................................................................................... 28 3.5.3. Runtime values............................................................................................................ 29 3.5.4. Dependent parameters ................................................................................................. 30 3.5.5. Parameters with “ALL” value ..................................................................................... 31 3.5.6. Special __USER__ Parameter .................................................................................... 31

3.6. Query Designer .................................................................................................................33 3.7. Query Editor......................................................................................................................36 3.8. SQL Log Panel ..................................................................................................................39 3.9. Status Bar ..........................................................................................................................40 3.10. Report and Chart creation ...............................................................................................40 3.11. Wizard .............................................................................................................................41 3.12. Report Layout .................................................................................................................49 3.13. Alarm Reports .................................................................................................................65 3.14. Indicator Reports .............................................................................................................66 3.15. Report Templates ............................................................................................................67 3.16. Chart Layout ...................................................................................................................68 3.17. Publish & Download .......................................................................................................73

4. Advanced Topics .........................................................................................................................75 4.1. Internal Structure ..............................................................................................................75 4.2. Configuration ....................................................................................................................76 4.3. Adding support for your language ....................................................................................79 4.4. Adding support for other JDBC driver .............................................................................80 4.5. Annex ................................................................................................................................83

1

Chapter

1 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, rtf, text-csv, tsv, web-html, xml and txt). (See chapter 3.Usage Report Layout Section). 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).

Introduction

2

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.

3

Chapter

2 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.

Installation

4

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.

Installation

5

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.

Installation

6

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.

7

Chapter

3 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.

Usage

8

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, pdf, csv, tsv or xml. 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.

Usage

9

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.

Usage

10

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.

Usage

11

ATTENTION Even the database password is encrypted, we recommend using some safe ways to transfer the exported xml file.

Favorites menu 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 :

Usage

12

- 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.

- 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 … allows importing data sources and all queries, reports and charts from an older version of NextReports

ATTENTION This operation can be performed for older versions of NextReports starting with 2.0. See installation chapter for what folder to select.

- Settings allows 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

Usage

13

- 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 shows the 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

Usage

14

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.

Usage

15

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:

Usage

16

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.

Usage

17

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 - Export Report - Run Report (to html, excel, pdf, 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)

Usage

18

- 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 , 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.

Usage

19

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.

Usage

20

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, 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.

Usage

21

URL field (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. Auto connect after save (7) is not a persistent field. It just informs the user, that after data source 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.

Usage

22

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

Usage

23

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.

Usage

24

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.

Usage

25

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.

Usage

26

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. Selection field(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.

Usage

27

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) Preview value field (2) is the value that the procedure used internally to exit as fast as possible making the process of finding the return columns faster. (see Query Editor section)

Usage

28

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.

Usage

29

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.

Usage

30

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.

Usage

31

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:

Usage

32

….. 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!).

Usage

33

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

Usage

34

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.

Usage

35

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.

Usage

36

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 willrun 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 textfield 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.

Usage

37

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.

Usage

38

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.

Usage

39

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.

Usage

40

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.

Usage

41

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 and indicators 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.

Usage

42

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 or indicator. Second step is the one of data source selection.

Usage

43

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.

Usage

44

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.

Usage

45

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

Usage

46

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.

Usage

47

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>.

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

Usage

48

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

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

Usage

49

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 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.

Usage

50

- Page Footer: Page Footer rows are generated for PDF 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 or indicator. Table, alarm and indicator 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 and rtf formats 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 4. Orientation : portrait or landscape, used by pdf and rtf formats

Usage

51

5. Padding : document margins in pixels used by pdf, rtf and excel formats 6. Header on every page : used by pdf, rtf and excel formats 7. Background image : used by pdf and html formats

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.

Usage

52

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). 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.

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.

Usage

53

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

‘New page’ property specifies that exported row from that band will always start on a new page. This property has meaning for PDF, 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:

Usage

54

User can create a new expression using button, or he can select an already defined expression using button. 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, RTF and EXCEL documents) TOTAL_PAGE_NO : total number of pages for PDF document

Usage

55

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.

- 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.

Usage

56

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 ; }

Usage

57

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 > Function : insert a function (this is possible inside report footer band, inside group

footer bands, inside report header band, inside group header bands)

Usage

58

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. 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 > Barcode : insert a barcode. User can select a barcode type and a value entered by

hand or taken from a database column.

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)

Usage

59

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. 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)

Usage

60

- 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.

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

Usage

61

- 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 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” otpion can be modified. - 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.

Usage

62

- 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 - PDF - RTF - XML - CSV (comma separated values) - TSV (tab separated values) - TXT (flat text file with fixed character widths for columns)

Usage

63

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. 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.

Usage

64

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

Usage

65

3.13. Alarm Reports “Alarms” are special types of reports that can be published to a NextReports Server. Inside designer they must have two 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)

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 <= 0 , background color is red, otherwise background color is green. Expression in the second cell is defined as :

if ( $C_NUMBER_PC <= 0 ) { "Alarm!"; } else { "Ok"; }

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 .

Usage

66

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 three cells:

• Title indicator • Description (optional) • Unit (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.

Usage

67

3.15. 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.

Usage

68

3.16. 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 or area. When create a new chart, default type is bar.

Usage

69

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.

- 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)

- 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

Usage

70

- 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.

- 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.

Usage

71

- 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

- 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 they axis itself

Usage

72

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 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.

Usage

73

3.17. 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.

Usage

74

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’ or ‘indicator’ type, if no default values for parameters are selected, the report will not be shown on server in the list of alarm or indicator 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

75

Chapter

4 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.

Advanced Topics

76

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

Advanced Topics

77

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!

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.

Advanced Topics

78

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 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

Advanced Topics

79

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

Annex

80

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);

Annex

81

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"; } }

Annex

82

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.

Annex

83

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-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

Annex

84

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