From Developer Community

Contents 1 Reports 1.1 Overview 1.2 A Note About Jasper Reports 1.3 Getting Started 1.4 Building the Plug-in 1.5 Development Process 2 Editing A Report 2.1 Adding Data to the Report 2.1.1 Adding Data From the Database 2.1.2 Adding Data From the Sentinel Log Manager Event Store 2.2 Parameters 2.2.1 Implementing Cascading parameters 2.3 Adding Charts to Reports 2.4 Fonts 2.5 Previewing a Report 2.5.1 Plug-in Documentation Template

Reports

UNDER CONSTRUCTION

NOTE: Some of the information found on these pages is dependent on having the not yet released Sentinel Log Manager 1.0.0.3 installed. The following features will not work without Sentinel Log Manager 1.0.0.3 installed:

• Top N type reports
• The "EventTag" parameter type
• The ability to preview an SLM events report from within iReport

Overview

Sentinel RD and Sentinel Log Manager (collectively we'll refer to them as Sentinel) include a reporting engine that allows users to generate reports that display data queried from the server. The reporting engine utilizes the open source Jasper Reports engine in order to define and generate reports that display the data in a nicely formatted layout. Many report definitions are included out of the box. It is possible, however, to upload additional (custom) report definitions.

A Report definition is packaged in Sentinel in a form called a Report plugin-in. The plugin-in is a zip file that contains all the files required in order for the Sentinel reporting engine to run the report.

The aim of this page is to explain how to develop Report plug-ins that can be used with Sentinel RD and Sentinel Log Manager.

Sentinel 6.1 and prior releases used Crystal Report technology instead of Jasper. Developing Crystal Reports is not covered here.

A Note About Jasper Reports

Jasper Reports is an open source project that is available for everyone to use. The most basic part of a Jasper Report is its .jrxml file. This file contains the query to execute as well as how to format the results of the query. Formatting can include tables, columns, graphs, charts, etc.

Editing the .jrxml file can be done by hand, however since formatting can get quite complex, editing the file by hand is not recommended. iReport is a free, open source, program that provides a GUI development environment for editing .jrxml files and makes the task of editing .jrxml files significantly easier.

Both Jasper Reports and iReport are rich tools for developing and running reports. Since there is a lot of information about these tools already available on the Internet, we will not attempt to document all aspects of these tools here. Instead, this documentation will focus on what you need to know in order to use these tools with the Sentinel SDK.

Here are some links to more information on these tools. This list is not exhaustive, however, so a web search is recommended in order to find more information:

• Jasper Reports: http://jasperforge.org/plugins/project/project_home.php?projectname=jasperreports
• iReport: http://jasperforge.org/projects/ireport

Getting Started

This section assumes that you have already completed the setup steps detailed in SDK Pre-Requisites and SDK Installation and Configuration. It also assumes that you are going to create a new Sentinel Report plug-in using a report template provided by the Sentinel SDK.

To begin creating a new Sentinel Report plug-in:

1. In the Ant tab, double-click on the "new" entry under "Reports", and follow the prompts
   1. You will be prompted for few pieces of information. This information will be used to choose the best report template for your needs and populate your initial report with common meta-information.
      • Report category: The general category of report - this will be used for the first part of the report name. If matching an existing report category, make sure you type carefully or copy/paste.
      • Report name: The specific name of this report. Be clear as to what the purpose of the report is.
      • Report Query Type: The kind of data this report will query for. The option you select here will affect the next prompts.
        • Event: Select this option to create a report that will query for event data.
        • Configuration: Select this option to create a report that will query for configuration data.
        • Both: Select this option to create a report that can query for both event and configuration data (e.g., join them). This option is only available for reports that will run on Sentinel RD and Identity Audit because in Log Manager the configuration and event data are stored in different storage mechanisms.
      • Sentinel Platform: If prompted, select the Sentinel platform this report will run on. The platform either Sentinel RD, Sentinel Log Manager, or both. For Identity Audit, select Sentinel RD. Depending on the choice you made at an earlier prompt, you may have to choose a single platform or select that you want the report to run on multiple platforms. In most cases, a single report must be written for a particular platform because of the way the data storage mechanisms vary from platform to platform.
2. In the Package Explorer tab, select the "reports" project and hit F5 to refresh the listing
   • You should see your new Report development directory appear in the list under "reports" under the vendor and product names that you entered
   • The newly created report dev directory structure consists of:
     • <Category>: The grouping category for the report
       • <Report Name>: The name you have given the report
         • archive: old archived versions of the report
         • research: Any documents or other research used to help build the report
         • sample: A set of sample data that can be used to populate the report for testing
         • 6.1: Report dev directory
           • docs: contains release.odt, a templatized doc used to generate the report helpfile
           • parameters: Holds report parameters, see autoparam below
           • build.xml: Drag this over to the Ant tab to build the report
           • files.include: Comma separated list of files to include from the content/dev/reports/AA-common/src directory. This files should typically list at least the following two files:
           • Key_Color.csv: Creates a mapping between specific series labels and the colors that will be used to display them in charts. Add your own series labels here.
             • Color_RGB.csv: Master 'Color to RGB' mapping file used for charting and event names
             • plugin.properties/release.properties: meta-information files, typically no need to edit these
           • PieChart01.properties / TimeSeriesChart01.properties etc., (names can vary) are files used for customizing the charts placed in the report.
           • TemplateReport/Chart*.properties: localization files
           • TemplateReport.jrxml: Report source
           • TemplateChart.jrxml: Subreport source
           • TemplateReport.pdf: Sample report pdf

As you develop your report, additional files may be added including custom java classes, additional properties files, and so forth.

This procedure will clone the Report template to create a new skeleton Report in a development directory. You will edit the files in this new Report plug-in to add code, meta-information, documentation, and other key features.

Within this documentation, we refer to the .jrxml file as the report definition. The report definition contains all of the settings Jasper Reports needs to know in order to generate a report. Since there are a number of complexities in the report definition, it is best to start from a template report definition that has many of the common settings already setup. This way, you can focus on adding the specific query and formatting that you are interested in. To get started with the template, do the following.

Building the Plug-in

In order to build your plug-in from the development directory into a functional plug-in, perform the following steps within Eclipse:

1. Expand the "reports" project in the Package Explorer tab
2. Expand the directory that contains your Report development directory
3. Expand the "6.1" directory to reveal the development files
4. Drag the "build.xml" file in that directory over to the Ant tab
   • You should see a new Ant project with the name of your Report
5. Expand your Report under the Ant tab
6. Double-click on the "build" target and follow the prompts
   1. Select "n" when asked to increment the release number

• The resulting built plug-in and associated files will be created under the directory /proj/content/build/<plug-in name>.
• The plug-in will be named <plug-in name>_<template version>r<release version>.rpz
• This initial build is just to test that things are working; as you develop your plug-in you can rebuild as many times as you like to debug and test your work
• When development is complete, you can remove the project from the Ant tab to reduce clutter; if you go back to working on the same plug-in, you can re-drop the "build.xml" to the Ant tab

It is expected that you will build your plug-in many times during development; the build process is fully automated. In addition to the ant build command, which does a complete build, you can also use the ant build-zip which only builds the portion of the plug-in based on code (e.g. no documentation etc), for more rapid development cycles.

After building the Report, import it into your system using the web interface provided. The exacts steps for doing this various between Sentinel products. Refer to the product documentation for the exacts steps.

Development Process

The development process consists of:

1. Clone the template to make a new skeleton plug-in (see above)
2. Modify the development code (see below) and meta-information files
3. Build for test and debug (see above)
   • Repeat previous two steps
4. Perform a final build and release your plug-in

Editing A Report

Using iReport is the best method for editing report as it provides a rich IDE that allows you to customize virtually all aspects of the Jasper report.

1. Launch iReport.
2. Open up the TemplateReport.jrxml file in the report directory. There may also be other jrxml files in the report directory, which define subreports. This can also be edited.
3. Edit the report as needed.
   • If you created your report from a template using the instructions above, your report will by default consists of all the standard features which are most commonly used such as data section, sparkline chart, pie chart etc.
   • Depending on your requirements, you may need to edit either the report design (layout) or the query that is used to obtain the data to populate the report.
   • Tips on how to do some common jasper report tasks can be found below and on the JasperReportsDevelopment page.
4. When you are done, return to Eclipse to build the report into a plugin that can be imported the Sentinel system. For more information on building the report into a plugin, see the instructions at ReportImplementationGuidelines#Building_Report_Plugins.

Adding Data to the Report

Sentinel products store a variety of data that is useful to report on. This section explains the kinds of data stored in Sentinel products and where, in each product, the data and be found. The location of the data will affect the way the report query is written.

• Events: These are events that are generated as a result of parsing raw data coming from event sources. This also includes system (internal) events that are generated internally.
  • Sentinel RD and Identity Audit
    • Stored in an embedded PostgreSQL database.
  • Sentinel Log Manager
    • Stored on the filesystem. The event data is indexed using Lucene and, therefore, you must use a Lucene type query to query for this data. This is the same way event search works in the Log Manager (i.e., via the web UI). Event data is stored in this way because it is more highly optimized than a normal database.
• Configuration: This is all of the configuration settings. This includes event source management settings, system users, and other configuration settings.
  • All Sentinel products
    • Stored in an embedded PostgreSQL database.

Note also that many reports are heavily dependent on event taxonomy; filters and colors are often applied based on [[SentinelTaxonomy][that taxonomy]].

It is important to note that since these two kinds of data are stored in different locations and because a single Jasper report can query only one location at a time, a single Jasper report is limited to querying for either events or configuration data, but it cannot query for both. The data fields that can be included in a given report are defined by the database views that can be queried (plus any additional external data sources). The full list of database views is available in the Sentinel documentation, available on the Novell [[1][documentation site]]. (future link: Sentinel DB Views)

Adding Data From the Database

Since Jasper has built-in support for querying databases, developing a report to run against the Log Manager configuration database is just like writing a Jasper report for any system that queries a database. For example, when defining the query, there is no need to specify a language because by default the Jasper report engine will assume it is SQL: <queryString> <![CDATA[SELECT ...]]> </queryString>

In order to create a SQL query that will run against the Log Manager's database, you'll need to know the Log Manager database schema. You can find this schema here: {link needed} For more information about how to develop Jasper reports that query the database, use the following link: https://twiki.innerweb.novell.com/bin/view/SentinelDev/SentinelContentDev#Reports Data stored in an embedded PostgreSQL can be queried for using a normal SQL queries. The iReport manual contains a lot of information about how to add data to a report when the source of the data is a database, therefore refer to this manual for more information.

Adding Data From the Sentinel Log Manager Event Store

If you are writing a report for SLM, there is additional information you need to know beyond what is typically needed when writing a report that runs against a database. The reason is that SLM uses an optimized data store for events instead of a database. This additional information can be found here.

Parameters

Within iReport, you define custom report parameters to be used to control various aspects of report generation. Some of these parameters can be selected at report runtime, these are called "prompted parameters". In general, you need to "export" these parameters from the report itself to Sentinel's external parameter format so that the platform (e.g. Novell Identity Audit) can properly prompt for them. To do so:

1. Build the parameters you will need internally in iReport. Save the report.
2. Run the 'ant autoparam' target.
3. Review the generated parameters now stored in the 6.1/parameters directory under your report, add defaults and queries and options and descriptions and so forth, and save your changes.

For more details on the plug-in parameters, see Parameters.

Parameters used can be of various types such as String, Date etc., Most commonly used parameters are:

1. date_range: used to prompt various options for date range such as Current Day, Previous Day etc.,
2. FromDate / ToDate: used to accept input for 'Custom Date Range'.
3. locale: used to prompt for language to which report is to be localized.
4. PLUGIN_DIRECTORY: used to set the default path of the '.csv' files required for color externalization. This is set dynamically during report run time in platform(Identity Audit / Sentinel RD)
5. VendorProduct: used to set the name of the VendorProduct in reports which use the 'Collector' name to filter the records.

Parameters can also be dynamic, which can be retrieved using the SQL query as explained in 'Implementing Cascading parameters'.

The tag '<IsForPrompting>0</IsForPrompting>' can be used in parameters which are not intended for prompting to the user. Use 1 in place of 0 if we need to prompt that parameter.

Note that the order specified in the 'tempalte.pml' would define the order of parameters displayed in the parameter screen when running the report.

(Add discussion of localizing dates and times, etc)

Implementing Cascading parameters

Using the Cascading parameters syntax (described below), JasperReport Plugin developers can tie multiple report parameters together such that when the value of one parameter changes, any dependent parameters will be updated accordingly.

Suppose a report had two parameters

1. A "Department" combobox parameter by which the user running the report can select a "Departments" such as Engineering, Sales, or Support.
2. An "Employee" combobox parameter by which the user running the report can select an "Employee" in the currently selected "Department".

In this case, the employees listed "Employees" combobox should change based on the department selected in the "Department" combobox. Cascading report parameters are used with the previously existing "OptionQuery" parameter type. The OptionQuery parameter type allows you to specify a query that gets executed at run time to query the database and dynamically generate the options that get displayed in the parameter's combobox.

To support cascading parameters, the following syntax has been defined:

• To specify that an "OptionQuery" parameter is dependent on the currently selected value of another parameter, you just need to insert the internal name of the other parameter in place and enclosed in ##..## tags in the OptionQuery string.
• For example, in the following package.xml code snippet, note how ##CascadingOption1## is used in the OptionQuery parameter of the second parameter to indicate that it is dependent on the value of the first parameter:

  <PluginParameterDefinition> 
   <Type>String</Type> 
   <DisplayName>Cascading Option 1</DisplayName> 
   <InternalName>CascadingOption1</InternalName> 
   <Description>Select a plugin type.</Description> 
   <DefaultValue>JASPER_REPORT</DefaultValue> 
   <IsForPrompting>1</IsForPrompting>
   <PreventDuplicates>1</PreventDuplicates>
   <OptionQuery>SELECT SENTINEL_PLUGIN_TYPE AS NAME, SENTINEL_PLUGIN_TYPE AS VALUE FROM SENTINEL_PLUGIN</OptionQuery>
  </PluginParameterDefinition> 
 
  <PluginParameterDefinition> 
   <Type>String</Type> 
   <DisplayName>Cascading Option 2</DisplayName> 
   <InternalName>CascadingOption2</InternalName> 
   <Description>Select a plugin.</Description> 
   <IsForPrompting>1</IsForPrompting>
   <OptionQuery>SELECT SENTINEL_PLUGIN_NAME AS NAME, SENTINEL_PLUGIN_ID AS VALUE FROM SENTINEL_PLUGIN WHERE SENTINEL_PLUGIN_TYPE='##CascadingOption1##'</OptionQuery>
  </PluginParameterDefinition>

Some more notes:

1. Use ##<internal name>## within an OptionQuery string to specify the internal name of the parameter whose value is to be dynamically inserted into the query string.
2. At this time, only one ##<internal name>## can be specified in a single OptionQuery string.
3. At this time, there is technically NO LIMIT to the number of parameters that can be cascaded.
4. Note how a new "PreventDuplicates" option has been added to the PluginParameterDefinition. If this flag is set to "1" (true), then when the optionquery is being executed, any options with duplicate values will be stripped out. If this flag is set to "0" (false), then when the optionquery is being executed, all options will be added (even duplicates).
5. Again, take a look at jserver/das/tests/misc/CascadingParameterTest.zip as an example.

Adding Charts to Reports

Jasper includes the <nop>JFreeChart charting library as part of its solution, but we have significantly extended that to support more useful chart types and to match our design aesthetic. In general you should use the SentinelJasperCustomCharts to build charts for your reports.

Relevant link which lists out the various customizations researched on the charts: JasperReportsResearchTasks

Fonts

Reports are typically viewed as a PDF when they are generated. In order for unicode characters to display properly in the PDF, reports must use one of the following fonts:

• Arial
• Arial Unicode MS

Only these fonts are mapped to a PDF font (arialuni.ttf/Arial Unicode MS) and PDF encoding (Identity-H) that are capable of displaying unicode characters. NOTE: The PDF mapping above has been implemented in Pilin, Sakura, Sentinel 6.1.1.1, and Identity Audit 1.0.0.2 and above. Earlier versions don't display unicode characters properly.

Previewing a Report

After you've done a certain amount of development work on your report, it's a good idea to preview the report in iReport to make sure it works properly.

1. Make sure you've performed all the development environment setup instructions specified at [[Sentinel Development Environment|SDK Pre-Requisites].
2. Tips for running reports
   • Unless you want to the report against a specific product, use "" (empty string, including quotes) for the Vendor Product parameter.
   • Error Workarounds
     • You may see an error in the "Problems" output tab of iReport that states "Class com.novell.reports.jasper.data.event.LuceneEventQueryExecutorFactory not found". As long as all of the above steps are followed properly, things should still work properly. This seems to be a bug in iReport related to some parts of the UI not honoring the classpath set in the instructions above.
     • Because of the way the parameters are defined, you will likely get an error if you attempt to run a sub-report directly. Instead, run the main report directly. Advanced users may be able to modify the parameter definitions in the sub-report to allow them to be run directly, however this has not been confirmed.

Plug-in Documentation Template

(follow heading link)

• Back up to Develop to Sentinel

• Article
• Discussion
• Edit
• History

Personal tools