Visualisation of network topology by integrating Maat with mapgl

The Maat application, combined with the Mapgl plugin in Grafana, enables the creation of detailed network topology visualizations. By entering specific network data into Maat and using the MaatDex script to export that data in a compatible format (JSON or CSV), it is possible to build clear and interactive visual maps of network infrastructure in Mapgl. This process allows for linking geographical locations, network devices, interfaces, and services into a coherent visual representation that supports analysis, monitoring, and planning.

Network Topology Network Topology 3D

Example data model for the Mapgl plugin

Mapgl Data Diagram Below is an example of data entered into Maat for a simple topology consisting of two locations, two devices, two interfaces, one link, and two SAPs.

Mapgl Import Result

The following steps present how to store data in Maat using REST API (documentation and examples are here). Data can also be added by MaatUI.

Step 1 — Create two locations (category: `site`)

{
    "category": "site",
    "description": "Poznan",
    "name": "Poznan",
    "resourceCharacteristic": [
        { "name": "gps", "value": "52.40637400000000;16.92516810000000" },
        { "name": "city", "value": "Poznań" }
    ],
    "@schemaLocation": "https://bitbucket.software.geant.org/projects/OSSBSS/repos/maat-schema/raw/TMF639-ResourceInventory-v4-pionier.json",
    "@type": "PhysicalResource"
}

{
    "category": "site",
    "description": "Warszawa",
    "name": "Warszawa",
    "resourceCharacteristic": [
        { "name": "gps", "value": "52.22967560000000;21.01222870000000" },
        { "name": "city", "value": "Warszawa" }
    ],
    "@schemaLocation": "https://bitbucket.software.geant.org/projects/OSSBSS/repos/maat-schema/raw/TMF639-ResourceInventory-v4-pionier.json",
    "@type": "PhysicalResource"
}

Result: Keep the returned id and href for both locations. These will be needed for relationships (bref:site).

Sites in MaatUI

Step 2 — Create two devices (category: `device.router`) with back-reference to the location

{
    "category": "device.router",
    "description": "Router Poznan",
    "name": "mx-poz-1",
    "@schemaLocation": "https://bitbucket.software.geant.org/projects/OSSBSS/repos/maat-schema/raw/TMF639-ResourceInventory-v4-pionier.json",
    "@type": "PhysicalResource",
    "resourceRelationship": [
        {
            "relationshipType": "bref:site",
            "resource": {
                "id": "<Poznan-site-id>",
                "href": "<Poznan-site-href>",
                "name": "Poznan"
            }
        }
    ]
}

{
    "category": "device.router",
    "description": "Router Warszawa",
    "name": "mx-war-1",
    "@schemaLocation": "https://bitbucket.software.geant.org/projects/OSSBSS/repos/maat-schema/raw/TMF639-ResourceInventory-v4-pionier.json",
    "@type": "PhysicalResource",
    "resourceRelationship": [
        {
            "relationshipType": "bref:site",
            "resource": {
                "id": "<Warszawa-site-id>",
                "href": "<Warszawa-site-href>",
                "name": "Warszawa"
            }
        }
    ]
}

Result: Keep id/href for mx-poz-1 and mx-war-1.

Devices in MaatUI

Step 3 — Create interfaces and assign them to devices (category: `interface`)

{
    "category": "interface",
    "description": "== Warszawa ==",
    "name": "et-0/0/1",
    "resourceCharacteristic": [ { "name": "speed", "value": "400G" } ],
    "@schemaLocation": "https://bitbucket.software.geant.org/projects/OSSBSS/repos/maat-schema/raw/TMF639-ResourceInventory-v4-pionier.json",
    "@type": "PhysicalResource",
    "resourceRelationship": [
        {
            "relationshipType": "bref:device.router",
            "resource": {
                "id": "<mx-poz-1-id>",
                "href": "<mx-poz-1-href>",
                "name": "mx-poz-1"
            }
        }
    ]
}

{
    "category": "interface",
    "description": "== Poznan ==",
    "name": "et-0/0/5",
    "resourceCharacteristic": [ { "name": "speed", "value": "400G" } ],
    "@schemaLocation": "https://bitbucket.software.geant.org/projects/OSSBSS/repos/maat-schema/raw/TMF639-ResourceInventory-v4-pionier.json",
    "@type": "PhysicalResource",
    "resourceRelationship": [
        {
            "relationshipType": "bref:device.router",
            "resource": {
                "id": "<mx-war-1-id>",
                "href": "<mx-war-1-href>",
                "name": "mx-war-1"
            }
        }
    ]
}

Result: Keep the returned id and href (will be linked to SAPs).

Interfaces in MaatUI

Step 4 — Create network.core.link service

{
    "category": "network.core.link",
    "description": "PIONIR MPLS core link",
    "name": "mx-poz-1_mx-war-1",
    "@schemaLocation": "https://bitbucket.software.geant.org/projects/OSSBSS/repos/maat-schema/raw/TMF638-ServiceInventory-v4-pionier.json",
    "@type": "Service"
}

Result: Keep service id/href (needed for SAP1/SAP2).

Link in MaatUI

Step 5 — Create network.core.sap (SAP1) linking interface and link

{
    "category": "network.core.sap",
    "description": "mx-war-1",
    "name": "mx-poz-1_mx-war-1_SAP1",
    "@schemaLocation": "https://bitbucket.software.geant.org/projects/OSSBSS/repos/maat-schema/raw/TMF638-ServiceInventory-v4-pionier.json",
    "@type": "Service",
    "serviceRelationship": [
        {
            "relationshipType": "bref:network.core.link",
            "service": {
                "id": "<link-id>",
                "href": "<link-href>",
                "name": "mx-poz-1_mx-war-1"
            }
        }
    ],
    "resourceRelationship": [
        {
            "relationshipType": "bref:interface",
            "resource": {
                "id": "<et-0/0/1-id>",
                "href": "<et-0/0/1-href>",
                "name": "et-0/0/1"
            }
        }
    ]
}

Step 6 — Create network.core.sap (SAP2) linking interface and link

{
    "category": "network.core.sap",
    "description": "mx-poz-1",
    "name": "mx-poz-1_mx-war-1_SAP2",
    "@schemaLocation": "https://bitbucket.software.geant.org/projects/OSSBSS/repos/maat-schema/raw/TMF638-ServiceInventory-v4-pionier.json",
    "@type": "Service",
    "serviceRelationship": [
        {
            "relationshipType": "bref:network.core.link",
            "service": {
                "id": "<link-id>",
                "href": "<link-href>",
                "name": "mx-poz-1_mx-war-1"
            }
        }
    ],
    "resourceRelationship": [
        {
            "relationshipType": "bref:interface",
            "resource": {
                "id": "<et-0/0/5-id>",
                "href": "<et-0/0/5-href>",
                "name": "et-0/0/5"
            }
        }
    ]
}

SAPs in MaatUI

MaatDex — Export data for Mapgl

Once objects are in Maat, run MaatDex to export data. It generates JSON or CSV for Mapgl import.

Example JSON Output

[
  {
    "vertexA": "Poznan",
    "vertexB": "Warszawa",
    "edgeId": "f62c500e-9194-466a-bd13-556d9a84106b",
    "lon": 16.9251681,
    "lat": 52.406374,
    "devif": "mx-poz-1 et-0/0/1",
    "bandwidth": 400000000000,
    "thickness": 5,
    "description": "PIONIR MPLS core link",
    "city": "Poznań",
    "link": "mx-poz-1 <-> mx-war-1"
  },
  {
    "vertexA": "Warszawa",
    "vertexB": "Warszawa",
    "edgeId": "",
    "lon": 21.0122287,
    "lat": 52.2296756,
    "devif": "",
    "bandwidth": 0,
    "thickness": 0,
    "description": "",
    "city": "Warszawa",
    "link": ""
  }
]

Mapgl — Import data

Instructions for Importing the Mapgl Panel in Grafana

Importing the Basic Topology

Create a new folder in the Dashboards menu (e.g., Example) and click the Import button.
Import the selected JSON file containing the prepared dashboard.
For starters, it’s best to choose the version without VictoriaMetrics integration – file:
Network Topology - Mapgl - without VictoriaMetrics.json
Click the Edit button in the Network topology panel.
Paste into the appropriate field the URL of the public repository containing your exported topology prepared using the MaatDex script.

✅ Done! The result will be visible after refreshing the panel.
Step 4

Below is a more advanced example for the PIONIER network. PIONIER topology

Importing Additional City-Specific Topologies (PIONIER Example)

In the Example folder, create a new folder – e.g., Additional topologies.
Import a new dashboard.
Important – during import, change the UID so that it ends with the city name for this topology.
(Note: You can only change the UID during the import process)
Paste the address of the additional topology and, in the Layer type tab, select the Node Graph option.
Results:
Go back to the main topology and open the Queries tab.
In the Computed columns, Filter, Group by option, change the UID (for additional topology) for the selected expression (keep only the beginning of the UID without the city name).
Click on the selected node for which the new topology was created, and click the Drill-down button.
You will be redirected to the dashboard containing the topology for your city.