Help

Index Home > Report > Edit > Templates

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.

Files

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)
  • description
  • section(name)
    • description
    • usage
    • input(label, name, type, [value, required])
    • script

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>

Scripting API

The scripting language is JavaScript(v1.6 with E4X), with the following extra classes defined:

• 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 "&lt;"
• "&" should be written as "&amp;"