7.2.3. Report Scripting Framework

Allows for writing reusable report modules that can be invoked by the Axivion Dashboard for interactive report creation as well as via the command-line utility report_runner.py or via custom command-line utilities for manual report creation.

Related modules

axivion.dashboard.report

Main Module of the Dashboard Reporting API.

7.2.3.2. Getting started

A valid reporting module must define the factory method create_report_writer(report_runner) returning an instance of an implementation of the interface ReportWriter and the python file must match the pattern report_*.py.

The Reporting Frameworks also offers a standardized way for modules to declare options they accept that then can be supplied conveniently via command line or the Dashboard UI. See Writer.get_options() and Option for details on how to declare such options.

Currently a minimal valid report module could look like this:

# Copyright (C) 2025 Axivion GmbH
# Copyright (C) 2025 The Qt Company GmbH, a subsidiary of The Qt Group
# https://www.qt.io


from typing import Tuple

from axivion.dashboard.report import (
    Option,
    Report,
    ReportApiVersion,
    ReportRunner,
    ReportWriter,
)


def create_report_writer(_report_runner: ReportRunner) -> ReportWriter:
    '''Factory method called by the reporting framework module loader'''
    return MyReportWriter()


class MyReportWriter(ReportWriter):
    def report_api_version(self) -> ReportApiVersion:
        return ReportApiVersion(3, 0)

    def get_description(self) -> str:
        return "A simple example report script"

    def get_options(self) -> Tuple[Option, ...]:
        return (
            Option.text(
                name="example", default="Hello World!", description="an example option"
            ),
            Option.text(
                name="outfile",
                default="report.txt",
                description="name of the report file",
            ),
        )

    def write_report(self, context: Report) -> None:
        report_data = context.get_option_value('example')
        report_file = context.get_option_value('outfile')
        context.get_sink(report_file).write(report_data.encode('utf-8'))

Of course in order for this to do something useful, in the ReportWriter.write_report() method you will want to make use of the axivion.dashboard.Project instance supplied via Context.get_project() in order to fetch the metric values or issue lists you are interested in for your report.

There are various ways to write actual report data, see Report. Basically the only restriction is, that the report in the end needs to be a single file.

7.2.3.3. Report Runner

Once you have written your report module you can save it to a python file, e.g. report_simple.py. Note, that valid report module files must be prefixed with report_ and end in .py.

You can then list the possible options of your module like this:

report_runner options report_simple.py

For our example module the output then would be similar to this:

Module Options:

example              default: Hello World!
    an example option

outfile              default: report.txt
    name of the report file

You can then start the actual report creation in various ways, e.g.:

report_runner create --database path/to/analysis.db
              report_simple.py example="Hello again!"

This command reads the analysis data directly from a database file and specifies a non-default value for the module option example. All values not specified on create invocation will be used with their defaults.

Very often, you don’t have a database file directly at hand but access to a Dashboard containing the analysis data. If so, you can do:

report_runner create
    --dashboard http://dashboard.example.com/
    --project <project>
    --username <yourusername>
    report_simple.py

For other ways to authenticate with the Dashboard see the help of the report_runner create action:

report_runner create --help

Note, that there is a special parameter to the create action allowing you to specify most options that you can give via commandline from a file as well. The file needs to have JSON format and could look like this:

{
    "dashboard": "http://localhost:9090/axivion",
    "project": "name-of-dashboard-project",
    "username": "your-user-name",
    "options": {
        "example": "report contents",
        "outfile": "report.txt"
    }
}

An example invocation then could look like this:

report_runner create --input options.json
    report_simple.py example="override the file value"

Here we have read the options to the create command from a file but overridden part of it via command line.

In order to quickly get a skeleton for such an input file, you may want to do the following:

report_runner options --format json report_simple.py > options.json

7.2.3.4. Multi-Value Options

Report modules can also accept multi-value options:

def get_options(self) -> Tuple[Option, ...]:
    return (
        Option.list(
            name='rules',
            description='Which rules should the report consider?',
            element_type=Option.text(
                name='rule',
                description='A rule name, e.g. MisraC2012-10.3',
            ),
            min_length=1,
        ),
    )

Those are given in input.json as a json list-value and on commandline via a comma-separated list:

report_runner create --input options.json
     report_simple.py rules=MisraC2012-10.3,MisraC2012-10.4

7.2.3.5. Local library inclusions

You may want to share python-code between several report modules or simply organize your module code into several python files for better maintainability. In that case you can do so, without the need for making these python library modules explicitly known to your python installation or by extending the python module search path. To that end, the reporting framework supports the use of relative python imports, i.e. if you use the directive:

from . import library

inside your module file, then a file called library.py located next to your module file will be imported.

7.2.3.6. More advanced examples

Various example report scripts are provided in the examples/reports sub-directory which can be found in the Axivion Suite installation directory. Find below explanations for some of them.

report_his_html.py

Creates a tabular report of system-wide HIS Metrics.

report_metrics_csv.py

Writes system wide project metrics as CSV.

report_misra_pdf.py

Creates a PDF file containing various tables and charts detailing how well your project does regarding the Misra rules it has enabled.

report_misra_xlsx.py

Creates an excel spreadsheet containing the number of violations per misra rule of a selectable MISRA standard.

report_delta_mailer.py

Does globally controlled e-mail sending in the context of the continuous integration instead of in the context of the dashboard like the Erosion Notification System does.