5.1.2.7. Custom Visualizations

Project erosion data can be displayed on the Dashboard Page in various visualization formats—graphs, charts, tables, images, etc—by creating custom scripts that fetch and process the relevant data from the Dashboard API.

Custom visualization examples

Dashboard page with custom visualizations.

Caution

Depending on the amount of data processed by visualization scripts, this feature may place a noticeable load on the server; however, visualization results are cached between page loads to maintain server responsiveness. Furthermore, if the generated visualizations contain a large amount of data that needs to be processed on the client side—e.g., complex SVG graphics with many shapes and paths—browser performance may degrade on the Dashboard Page.

To add custom visualizations, the Visualization Creation Interface must be enabled and configured on the Reporting > Custom Visualizations page of the general settings.

Note

Starting with 7.11, the Visualization Creation Interface is enabled by default for newly created Axivion Dashboard Server configurations, with the module search path set to <confdir>/modules. Additionally, this directory is populated with a set of example scripts.

Adding your own visualization scripts

A custom visualization is a Python script whose file name matches the pattern visualization_*.py and which defines a create_visualization_writer() factory method (see Section 7.2.4 for the programming details). For the Dashboard to discover such a script, the script file must be placed in the Module Folder that the Visualization Creation Interface is configured to scan:

  1. Open the Visualization Creation Interface on the Reporting > Custom Visualizations page of the general settings and make sure that it is enabled. Take note of the Module Folder setting: it is a filesystem path relative to the Dashboard configuration directory—the directory referred to as <confdir> below and passed to the server via dashserver ... --confdir <confdir>.

    The default value of the Module Folder depends on how the configuration was created:

    • For Dashboard configurations newly created with version 7.11 or later, it is modules, i.e., scripts are placed into <confdir>/modules.

    • Configurations that were migrated from a version prior to 7.11 keep their previous folder visualization_modules, i.e., <confdir>/visualization_modules.

    You may change the Module Folder to any path relative to <confdir> and save the settings.

  2. Place your visualization_*.py script inside that folder on the Dashboard host. For example:

    <confdir>/modules/visualization_my_chart.py
    

    The supplied example scripts are a good starting point. Starting with version 7.11.0, they are copied automatically into the default Module Folder (<confdir>/modules) during Dashboard setup (cf. Migration to 7.11.0), so in a default configuration you can simply duplicate one of them in place and adapt it to your needs.

  3. Add or configure a Custom Visualization gadget on the Dashboard Page. The Module Folder is scanned whenever a custom visualization is configured, so the newly added module is immediately selectable—no server restart or page reload is required.

Caution

The Module Folder is scanned for Python scripts that are executed on the Dashboard host. Make sure that only trusted users have write access to this folder; otherwise, malicious Python code could be run on the server.

In order for a user to customize the project portal on the Dashboard Page, they must be granted the Manage Portal permission. Additionally, the Generate Reports permission is required to add Custom Visualization Gadgets.

Custom visualization examples

Visualizations can be added to the project portal via Custom Visualization gadgets (cf. Section 5.1.4.3).

Similar to Custom Report Scripts, visualization scripts support configurable parameters that can be set through the UI and that are stored along with the gadget. After portal configuration is complete, all users will see the same gadgets for all projects; i.e., there exists only one portal configuration, and regular users will not be able to change it.

More details on creating new report modules can be found in Section 7.2.4.