From OpenNMS

"Database Reports" is a section in the webUI, and a handy term to refer to reports that don't fit well into other categories. A "Report Service" can be integrated into OpenNMS by implementing a simple Report API. At this point, two report services have been implemented:

• The availabilityReportService is a wrapper around the old-style OpenNMS Availability reports. This was implemented as a test for the Report API and also to prepare for this capability to eventually be replaced by something rather more flexible.
• The jasperReportService is a wrapper around the JasperReports engine. These notes focus on the jasperReportService only.

Contents 1 JasperReports Configuration Example 1.1 global configuration 1.2 service-specific configuration 2 handling parameters in JasperReports 3 Reports 3.1 Database reports 3.2 Performance reports 4 Version History/Availability

JasperReports Configuration Example

global configuration

Because of the need to support multiple Report Services, there are two configuration file entries for each report. Configuration details to all Report Services including the way in which it's identified in the webUI, the Report Service it uses and whether it can be run interactively are included in database-reports.xml. Other, service specific configuration details are included in a service specific configuration file The incomplete snippet shows only one report defined in database-reports.xml:

<database-reports>
  <report id=“Early-Morning-Report” 
    display-name=“Early morning report”
    online=“true”
    report-service=“jasperReportService”
    description=“Ronny’s Awesome Report” />
</database-reports>

• id - unique identifier that allows the report to be located in service specific configuration files, and when the report is scheduled to run in the future.
• display-name - the name that the report will be identified by in the webUI.
• online (either 'true' or 'false'). Determines whether the report will be included in the list of reports that can be run immediately or whether it will only be available as a batch report.
• report-service - the name of the Report Service used, currently "jasperReportService" or "availabilityReportService". This example is a JasperReport.
• description - some handy text that explains what the report does.

service-specific configuration

As this report uses the jasperReportService, it will also require an entry in jasper-reports.xml, the service-specific configuration file:

<jasper-reports>
	<report id=“Early-Morning-Report”
		template=“Early-Morning-Report.jrxml”
		engine=“jdbc” />
</jasper-reports>

• id - the unique identifier from database-reports.xml
• template - the file name of the template used (templates are stored in $OPENNMS_HOME/etc/report-templates.
• engine - the report engine used, either jdbc or null (this will almost always be jdbc - these are supposed to be 'database reports' after all).

OpenNMS will automatically pick up the change and make your new report available for immediate use.

handling parameters in JasperReports

This feature is only available in the feature-report-api-parameters branch at the time or writing (23/12/2010)

JasperReports supports the notion of report parameters that can be prompted for at the time the report is run. OpenNMS currently supports the following promptable parameter types for JasperReports:

• java.lang.String
• java.lang.Integer
• java.lang.Double
• java.lang.Float (not sure why I did this)
• java.util.Date
• java.sql.Timestamp

Below is an example of the way you would define a promptable Double parameter with a default of 99.99 (slightly ambitious, perhaps) in your JasperReport:

<parameter name="doubleParameter" class="java.lang.Double">
    <parameterDescription>
       <![CDATA[a Double parameter]]>
    </parameterDescription>
    <defaultValueExpression>
      <![CDATA[new Double("99.99")]]>
    </defaultValueExpression>
</parameter>

• parameterDescription allows you to set a friendly name which the webUI will use to prompt for the value.
• defaultValueExpression does what you'd expect. It needs to be an instance of the parameter's class.

Note that JasperReport parameters have an attribute 'isForPrompting' which defaults to 'true'. If you have a parameter in your report that you don't want to prompt for, then you definitely need to set isForPrompting="false".

Finally, if you intend to use a String parameter to hold an OpenNMS category (not a report category), you can set a custom property on the parameter to tell the weUI to display a drop-down selector containing all the categories defined to OpenNMS:

<parameter name="categoryParameter" class="java.lang.String">
  <property name="org.opennms.report.stringInputType" value="onmsCategorySelector" /> 
  <parameterDescription>
    <![CDATA[a drop-down category parameter]]>
  </parameterDescription>
</parameter>

org.opennms.report.stringInputType can currently have a value of "onmsCategorySelector" or "reportCategorySelector". In reality, you'll only ever likely to need the former.

Reports

(taken from 1.8.8 snapshot db report list)

Database reports

• Early morning report

• Event analysis report
  • added from etc/report-templates into jasper-reports.xml and database-reports.xml
  • requires Postgres v8.4+

• Availability by node reports

• Availability summary report

Performance reports

(uses JRobin data)

• Response Time by node reports

• Response Time Summary reports

• Serial Interface Utilization Summary reports

• Total Bytes Transferred by Interface reports

• Average and Peak Traffic rates for Nodes by Interface

• 95thPercentileTrafficRate_subreport
  • uses RRD data

Version History/Availability

• This feature was added in version 1.8.8