Extending the product - Adding new report templates
This section describes how to author new report section templates, and add them to the product. This is an advanced topic, recommended for experienced users only.
By virtue of the scripting API, you can author new reports that have access to all the traffic data, topology, host locations and address mappings, as well as a choice of tabular or chart output. Even if the report you want involves several passes and elaborate data manipulation there is a good chance that it can be expressed, and once loaded it will appear just like any other report section that ships with the product. It can then be executed and scheduled in the normal way.
The report templates that ship with the product can be found under report/base/. These files should not be modified, however they can be copied to a new directory such as report/mycompany, and modified there. Any report templates found under report/*/ will automatically be made available through the web interface. If you use a distinctive name for your own reports directory, then you can offer your reports to other users, perhaps in the form of a .tar or .rpm file that they can install.
XML template format
A report template is an XML document, containing the following sections (and their properites):
- template(name, category)
- input(label, name, type, [value, required])
For example: here is a trivial template with just one section that will prompt for a host name and return its address:
<template name="example template" category="inventory"> <description>Example template description</description> <section name="DNS lookup"> <description>Get the IP address for a host</description> <input label="enter host" name="host" type="string" value="" required="true"/> <script> var report = new Report(); // use an instance of Network to do the lookup var network = new Network(); var name = network.ipAddressFromName(host); // create a table to arrange the output var table = Table.create(["address","name"], ["string", "string"]); table.addRow(new Array(name, host)); // add the table to the report report.table(table); </script> </section> </template>
- Query - provides access to the traffic database.
- Table - when you run a query, the result is always a Table.
- Network - provides lookup access to network state information such as address-mappings, host-locations and topology
- Chart - used to embed charts in reports.
- Report - used to collect charts, tables and text paragraphs into a report.
Please note that since the report template is an XML document, some characters that appear in your script may have to be escaped. For example:
- ">" should be written as ">"
- "<" should be written as "<"
- "&" should be written as "&"