7.2.3. Report Scripting Framework

Enables the creation of reusable report modules that can be invoked by the Axivion Dashboard for interactive report creation, via the report_runner.py command-line utility, or through 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), which returns an instance implementing the ReportWriter interface. The Python file must match the pattern report_*.py.

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

A minimal valid report module currently looks 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'))

To make the report useful, use the axivion.dashboard.Project instance provided via Context.get_project() within the ReportWriter.write_report() method to fetch the required metric values or issue lists.

Various ways to write report data are described in Report. The only basic restriction is that the final report must be a single file.

7.2.3.3. Report Runner

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

List the available options for your module as follows:

report_runner options report_simple.py

For the example module, the output will be similar to this:

Module Options:

example              default: Hello World!
    an example option

outfile              default: report.txt
    name of the report file

Start report creation using various methods, for example:

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 example module option. Any values not specified during the create invocation will use their defaults.

If you do not have a database file but have access to a Dashboard containing the analysis data, use the following command:

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

For other Dashboard authentication methods, refer to the help for the report_runner create action:

report_runner create --help

Note that the create action includes a special parameter allowing you to specify most command-line options via a JSON file, such as:

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

An example invocation would look like this:

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

In this example, options for the create command are read from a file and partially overridden via the command line.

To quickly generate a skeleton for an input file, run 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,
        ),
    )

These are provided in input.json as a JSON list and on the command line 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 organize your module code into several Python files for better maintainability. This can be done without making the Python library modules explicitly known to your Python installation or extending the Python module search path. The reporting framework supports relative Python imports; for example, if you use the directive:

from . import library

inside your module file, the file library.py located in the same directory as your module file will be imported.

7.2.3.6. More advanced examples

Various example report scripts are provided in the example/reports subdirectory within the Axivion Suite installation directory. Explanations for some of these scripts are provided below.

report_his_html.py

Creates a tabular report of system-wide HIS Metrics.

report_metrics_csv.py

Writes system-wide project metrics as a CSV file.

report_misra_pdf.py

Creates a PDF file containing various tables and charts detailing project compliance with the enabled MISRA rules.

report_misra_xlsx.py

Creates an Excel spreadsheet containing the number of violations per MISRA rule for a selected MISRA standard.

report_delta_mailer.py

Provides globally controlled email sending within the context of continuous integration, rather than within the dashboard as the Erosion Notification System does.

7.2.3.7. FAQ

Q: Why does the example CSV report script fail even though I have data in the dashboard?

A: Common causes:

  1. Missing metrics rules: The rules required by the report (e.g., Metric.Lines.Comment, Metric.McCabe_Complexity, Metric.Lines.LOC, Metric.Number_Of_Statements) are not activated in your configuration.

  2. Outdated configuration: The configuration may not have been updated to include all required metrics.

Solution:

  • Activate the required metric rules in your analysis configuration and run a new analysis, OR

  • Edit the Python report script (located at <AXIVION_INSTALLATION>/example/reports/report_metrics_csv.py) to include only the metrics that are available.