There are MANY NetXMS Reporting Server articles on Telegram and here on the Forum, as well as the Wiki and the Official Manual.

Most of them are either incomplete, old and out of date, or straight out wrong. For example the official manual at https://www.netxms.org/documentation/adminguide/reporting.html is, as of today,  incorrect.

This article is my attempt to write a reasonably detailed but complete set of steps to working with NetXMS Reporting Server on Ubuntu in 2021.  Its a bit of a rough brain dump, sorry. Please help me to edit and complete this, just reply to the thread.

Pre-requisites
On the Server

• A fully functioning NetXMS Server version 3.9.361 installed via the PPA on Ubuntu 18.04.6.
• Above NetXMS using Mysql (Mariadb should also work)
• Maven installed on your Ubuntu Server (apt install maven)
• SSH On your server so you can log in easily

On your PC

• Oracle Mysql Workbench (to make browsing and understanding the netxms db structure easy) if you are a guru with SQL on the CLI, maybe you dont need this, but I am a network guy not a DB or Java guy.
• Jasper Reports Studio community edition - you use this to actually write the report templates
• Mobaxterm (in my opinion the best Terminal Client for SSH to your server, and has a file manager built in so you can upload the report templates to the server.)
• Java JRE version 11
• NetXMS Management Console to match your NetXMS version
• Notepad++ - as editing xml files in regular windows notepad will not work
• Oracle Mysql Java Connector - so you can connect your Jasper Studio directly to your NetXMS MySQL. This makes using the query builder easy, and basically removes the need for the MySQL Workbench.

NetXMS Reporting Concepts:
1: NetXMS is leveraging the Jasper Reports engine, and this is tightly integrated with NetXMS server
2: The NetXMS Management Console is used to EXECUTE reports, but CANNOT CREATE reports.
3: You must change your perspective in the Management COnsole to the Reports Perspective
4: Management Console Server Configuration (nxmc) is used to configure the basic settings of NetXMS Report (nxreport)
5: You use the Jsaper Reports Studio on your PC to create report templates
6: You upload the files and folders of your Studio template to the server
7: Then you compile the report using MAVEN to create a .jar file, you must have a pom.xml and configure it correctly.
8: copy the .jar file to the NetXMS NXreportd definities folder, and restart services, this loads the template to the report server
9: Go to NXMC and execute the report either manually on schedule.
10: Right click the executed item and export as PDF or Excel.

Installing and Starting
To install the NetXMS Report server has now become extremely easy, and you must ignore almost all other articles on the net about how to install.

Install Procedure:

• SSH to your NetXMS Server.
• Run the command: sudo apt install netxms-reporting
• After the installation has finished set the service to start automatically at boot up
• Run the command: systemctl enable nxreportd.service
• Then execute systemctl start nxreportd

Enable Procedure
Now you must configure NetXMS to enable and use the report server.

• Log in to nxmc, go to CONFIGURATION > SERVER CONFIGURATION
• Use the filter function and search for Report
• Change the item ReportingServerHostname to 127.0.0.1 (this works around an issue where by default Ubuntu hosts file resolves localhost to ::1 for IPv6 but nxreportd is only listening on ipv4)
• Change the item EnableReportingServer to 1

At this point reporting server is installed and enabled. Lets check if it is working.

First, execute:

systemctl status nxreportd.service

you should see status running, and some log details.

Second, SSH to your server and execute

netstat -plantu | grep 4710

This should show you if the tcp port is open and an application (java) is listening there, result should look like:
tcp6       0      0 127.0.0.1:4710          :::*                    LISTEN      10802/java

If you dont see the port 4710 and the word LISTEN and the word java, go back and check with systemctl whats wrong the service.

Third, log in to nxmc and change your perspective to Reports perspective (top right corner of nxmc screen), once in press refresh on the Report Navigator side bar, nothing should happen and the list should be empty. If you get an error about communication then go back and check that the server configuration and nxreportd.service are ok and that netstat shows LISTEN

If all is good at this point, NetXMS Reporting server is installed and working, now you are ready to create and install some report templates.

Creating and Installing report templates.

Because we are all impatient, and because there is a learning curve to using Studio to create reports, it is interesting to play with some sample reports.

I like the empty report as it is simple and has nothing to break.

Download the sample reports from https://www.netxms.org/forum/installation/install-report-server/?action=dlattach;attach=2208 and save them to your PC

Exctract the archive (I use Peazip, it can read Zipped Tarballs).

Now open your Jasper Reports Studio, and open the main.jrxml file from within the sample_reports>empty>src>resources folder. This is the actual report template for a demo empty report.

Studio Concepts
1: When you save your template file it MUST be called main.jrxml
2: Best practice seems to be to put main.jrxml in a folder called resources which is in a folder called src, see image at bottom of post.
3: Read https://github.com/netxms/sample-report but note that the sample report in there is a demonstration of the PARAMETERS available, the report doesnt actually query netxms in anyway.
4: download the oracle java mysql connector on your PC, place it somewhere meaningful to you.
5: I have not succeeded to have images work in my templates, dont use them at the beginning. Report will compile but execution will fail on NetXMS
6: Connect your Studio to NetXMS  mysql server (you need to make mysql listen on all interfaces, and also make your Mysql user allow to connect remotely - out of scope of this howto).
7: You can run the reports in the preview tab quite well, and if you have connected studio to mysql it will return data, you can export these to pdf/excel from studio if you wish.
8: If you want to create and run one off reports just run them from Studio, if you want to have other users run reports and/or schedule them to be emailed then add the reports to NetXMS.
9: Take time to understand Jasper Reports concepts of Fields and Parameters.
10: Use the query builder to create your sql query, choose the data connector you installed earlier.
11: In query builder, once you have formulated your sql query press READ FIELDS from the top right. This will scan the query and the DB and populate the fields column below.
12: Review the fields and check that the class types for your data are what you expect.
13: Add Parameters in the parameter tab and tick the IS FOR PROMPT option if you want to enter parameters for your report, e.g. start date and end date for the report query.
14: When you are ready to publish this report (which you must do manually not using studio publish feature) then go to the source tab and remove the PROPERTY NAME that refers to your local data adaptor, NetXMS will use its own data adapter.

Now, in order for Maven to build your report in to a .jar file that you can place in NetXMS report server you must have a pom.xml file.

Use this one:

pom.xml

<project xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

  <modelVersion>4.0.0</modelVersion>
  <groupId>org.netxms.report</groupId>
  <version>1.0.0</version>
  <artifactId>user-list</artifactId>
  <packaging>jar</packaging>
  <name>User List</name>
  <url>http://www.netxms.org</url>

  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>

<dependencies>
  <dependency>
            <groupId>org.codehaus.groovy</groupId>
            <artifactId>groovy-all</artifactId>
            <version>2.4.4</version>
  </dependency>
</dependencies>

  <build>
    <resources>
      <resource>
        <directory>src/main/resources</directory>
        <excludes>
          <exclude>**/*.jasper</exclude>
        </excludes>
      </resource>
    </resources>
    <plugins>
      <plugin>
        <groupId>org.codehaus.gmavenplus</groupId>
        <artifactId>gmavenplus-plugin</artifactId>
        <version>1.4</version>
        <executions>
          <execution>
            <id>set-build-uuid-property</id>
            <phase>initialize</phase>
            <goals>
              <goal>execute</goal>
            </goals>
            <configuration>
              <scripts>
                <script>
                  import java.util.UUID
                  project.properties.setProperty('buildUuid', UUID.randomUUID().toString())
                </script>
              </scripts>
            </configuration>
          </execution>
        </executions>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-jar-plugin</artifactId>
        <version>2.5</version>
        <configuration>
          <archive>
            <manifestEntries>
              <Build-Id>${buildUuid}</Build-Id>
            </manifestEntries>
          </archive>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>


You must edit the following to suit your report:
<artifactId>user-list</artifactId>
<name>User List</name>
<directory>src/main/resources</directory>


Use a directory structure like the image at bottom of post, and place pom.xml in the root, this is the file structure BEFORE you use maven to assemble the final .jar file. Maven build process will place the META-INF and MANIFEST.MF in the correct place:


To build the report, execute from within the root structure of your project (where pom.xml is):

mvn package

This should build without errors, and create a folder called target with the resulting .jar file inside. This is what you will deploy to Nxreportd.

To deploy the report template, copy the .jar file in target directory to:

/var/lib/netxms/nxreportd/definitions

To check if it was deployed, run systemctl status nxreportd.service and read the log at the bottom.

Now restart netxmsd and nxreportd services.

Log back in to nxmc and go to report perspective, you should see your report listed in the report navigator. Click it and the execute it.

Hello.

First of all, thank you for your guide!

I have some suggestions which might be useful:

Pre-requisites:
- Java8 still works, but I highly recommend to use JRE11 or newer.
- Maven is required only for the development process, you don't need it for the deployment

NetXMS Reporting Concepts:

report template (.jar file) is just a zip archive with the following structure:
├── META-INF
│   ├── MANIFEST.MF
├── i18n.properties
└── main.jrxml

where "main.jrxml" is report entry point, you can add additional files (e.g. subreports or images) to the archive and reference them via $P{SUBREPORT_DIR}.

For example:
<subreport>
  <subreportExpression><![CDATA[$P{SUBREPORT_DIR} + "sub_report.jasper"]]></subreportExpression>
  ...


i18n.properties is a translation file for the report parameters, for example:

jrxml:
<parameter name="PERIOD_START" class="java.lang.Long">
      <property name="logicalType" value="START_DATE"/>
      <parameterDescription><![CDATA[Start of the Period]]></parameterDescription>
      <defaultValueExpression><![CDATA[1489356000L]]></defaultValueExpression>
   </parameter>


properties:
PERIOD_START = Start of the Period

META-INF/MANIFEST.MF contains 1 important attribute - "Build-Id" (GUID). This attribute is used to distinguish between deployed reports, so each deployed report should have unique ID (but report updates, usually have the same ID as previous version - this way you'll have all you history intact). Name might be misleading, now I'd call that report-id or something similar - but historical reasons.


Install Procedure:

You don't need to reboot server, just run "systemctl start nxreportd" or in previous stem run "systemctl enable --now nxreportd", this should be enough


Creating and Installing report templates:

Instead of using using groovy in pom.xml to generate random Build-Id on every invocation, I suggest to use static field and just update it if you are creating new report.
This was you'll have report history even if you have updated report definition. Sample: https://github.com/netxms/sample-report/blob/main/pom.xml

Source files (images, subreports, etc.) should be in src/main/resources or maven will not pick them up.


When (re)deploying report, you don't need to restart netxmsd, nxreportd will be sufficient.

Dear Alex,

Thank you for the info,  I will make some edits.

Question:

What is the procedure to REMOVE a report?

Do I just delete the .jar file from the /var/lib/netxms/nxreportd/definitions directory?

What about the directory where the report was expanded, must I delete that also, or will nxreportd remve that for me?

Also, when I re-deploy, can I just copy the .jar file and nxreportd will overwrite the contents of the directory already there?

Thanks,

Alex

ADDITIONAL NOTES Thanks to Alex K for the info, xposted from Telegram

Report Data Sources

1) Normally you use SQL queries directly to the DB, these should be formatted to suit your own SQL server implementation, if you migrate from one DB platform to another, you should expect to update your report templates, as the queries may no longer work, or work poorly.

2) You cannot currently use NXSL Scripting language directly in the report templates query builder, but you can use java. You can use a datasource java program to access the NetXMS API. See attached example.

Working in the Data Base

The Database tables called idata_XXXX are tables that contain DCI historical data. The Number after idata_ is an ObjectID (node id).

In recent versions of the reporting server you also have access to temporary view, which is created when report is executed, name of this view is passed as IDATA_VIEW report parameter and view is just:

select * from idata_X union all select * from idata_Y ...

- for all nodes in the system, so this way you can query specific DCI for nodes, for example - previously you'd have to use API for that.

For example in the Jasper Reports Studio query builder:

<parameter name="IDATA_VIEW" class="java.lang.String" isForPrompting="false">
      <defaultValueExpression><![CDATA["idata_view"]]></defaultValueExpression>
   </parameter>
...
   <queryString>
      <![CDATA[SELECT ...
FROM $P!{IDATA_VIEW} iv
LEFT JOIN items io ON io.item_id = iv.item_id
LEFT JOIN object_properties op ON op.object_id = io.node_id

Hi Everyone,
I got the server running but I am afraid my Jasper reports and java powers are limited.
The Alarm resolution works perfectly I found that somewhere in the forum. Sample is just that ..
Does anyone have some reports in .jar file format they are willing to share? Possibly a sticky topic with contributed reports?
Would be great if the server shipped with a few reports on installation!

Thank you  in Advance
Dawid

Hi Dawid,

Attached is user-list-1.0.0.jar already compiled. This report will output a list of the users in NetXMS and when they were created and last logged in.

Assuming you are using ubuntu with MySQL the following procedure:

Copy this .jar file to:
/var/lib/netxms/nxreportd/definitions

and restart nxreportd with:
systemctl restart nxreportd

Attached PDF shows what the output should look like. (edited for privacy)

Also attached is a zip file of the source of this report, it should build with no problems (as it has no dependencies) with:
mvn package

Note that java knowledge is not required. You can learn with some youtubes how to make a report in Jasper quite quickly, but you will need to learn some sql query code, and learn the data layout in the NetXMS dictionary.

This user report is simple because it just queries the users table with a simple:
SELECT * FROM netxms.users;

That is the query code in the Jasper Reports Query builder. You must modify this SQL query code to suit the Database Engine you are using.

Let me know if you struggle.

Quote from: Dawid Kellerman on November 27, 2021, 06:34:38 PM
Hi Everyone,
I got the server running but I am afraid my Jasper reports and java powers are limited.
The Alarm resolution works perfectly I found that somewhere in the forum. Sample is just that ..
Does anyone have some reports in .jar file format they are willing to share? Possibly a sticky topic with contributed reports?
Would be great if the server shipped with a few reports on installation!

Thank you  in Advance
Dawid

To comment on your request for other peoples examples of reports in .jar format, this is unlikely to work, because each persons NetXMS deployment will be slightly different. The idata_XXXX tables, Categories and myriad other things will vary from person to person, so the SQL queries that they use may not work for you.

The users list I shared above is a very standard thing, all netXMS have that table, and so it is reasonably safe to share that one.

So I would prefer if folks are willing to share sources of templates, and there are a few already.

It would be nice if there were a sticky like the other object and dci templates that are outthere.

A point on security here, if you do use somebody elses template, be sure to check the SQL code, as you dont want malicious SQL being used against your DB.

Best,

Alex

I would like to share with you my first report, which returns all the events other than a certain type of event ID that occurred to the nodes belonging to a certain container in a certain period of time.
I see there is a problem with converting timestamp from unixtimestamp and datetime, I will work on it in the next few days.
Enjoy it and feel free to let me know your opinion!

Fabrizio

Hi all,

May i know whether in latest NetXMS it already bundle with the feature to generate report such as utilization network device interface to .pdf? I means dont need to install additional package?

Thanks and appreciate any feedback