
[[topology-map]]
= Topology Map
:description: Learn how to configure the topology map in {page-component-title}, including icon mappings and creating new icons.

This section describes how to configure the topology map.

To view the topology map, click *Topology Map* in the side menu.

== Properties

The topology map supports the following properties.
You can configure them by editing `etc/org.opennms.features.topology.app.cfg`:

[cols="1,3,1,1"]
|===
| Property  | Description   | Type  | Default Value

| showHeader
| Defines if the {page-component-title} header is shown.
| Boolean
| true

| autoRefresh.enabled
| Enables auto-refresh.
| Boolean
| false

| autoRefresh.interval
| Defines the auto-refresh interval, in seconds.
| Integer
| 60

| hiddenCategoryPrefix
| Hides categories based on a defined prefix.
For example, a value of `server` hides all categories starting with "server".
Note that this setting is case-sensitive, so "Servers" will be shown. +
The resolution is enabled only if no longitude or latitude information is available.
| String
| _Blank_
|===

== Edge status

The choice of topology provider controls the status and color of an edge.
Each topology provider has different notions of what an edge represents, and may provide different controls for managing the behavior.

=== Linkd Topology Provider

The Linkd Topology Provider uses the state and existence of alarms to determine the color of an edge.
An edge between two vertices on a topology map represents a link that has been discovered between two interfaces on distinct nodes.
If an alarm is present with the UEI `uei.opennms.org/internal/topology/linkDown`, and the alarm is associated with either of the interfaces on either node, then the edge is red.
If no such alarm is present, the edge is green.

These alarms are not generated by default.
Enable them by setting the `logmsg` property in the `uei.opennms.org/internal/topology/linkDown` and `uei.opennms.org/internal/topology/linkUp` events to `logndisplay`.
These events are automatically generated by the default set of event translator rules that process incoming SNMP link up and down traps.

== Icons

An icon represents each vertex on the topology map.
The default icon is configured in `$\{OPENNMS_HOME}/etc/org.opennms.features.topology.app.icons.<topology-namespace>.cfg`.
If an icon mapping file does not exist for a topology provider, the provider does not support customization.

.List of available icon mapping files (may not be complete)
[source]
-----
org.opennms.features.topology.app.icons.default.cfg <1>
org.opennms.features.topology.app.icons.application.cfg <2>
org.opennms.features.topology.app.icons.bsm.cfg <3>
org.opennms.features.topology.app.icons.linkd.cfg <4>
org.opennms.features.topology.app.icons.vmware.cfg <5>
-----
<1> Default icon mapping.
<2> Icon mapping for the Application Topology Provider.
<3> Icon mapping for the Business Services Topology Provider.
<4> Icon mapping for the Linkd Topology Provider.
<5> Icon mapping for the Vmware Topology Provider.

Each file contains a mapping in the form of `<icon key> = <icon id>`.

* *icon key:* A topology provider-dependent string that maps to an `icon id`.
An icon key consists of one or multiple segments; each segment must contain only numbers or characters.
If multiple segments exist, they must be separated by a period (`.`) (for example, `my.custom.key`).
Any existing default icon keys are not configurable, and should not be modified.
* *icon id:* A unique icon identifier that references an icon within one of the available `.svg` files in `$\{OPENNMS_HOME}/jetty-webapps/opennms/svg`.

.`icon key` and `icon id` specification using BNF
[source]
----
icon key ::= segment["."segment]*
segment ::= text+ [( "-" | "_" | ":" ) text]*
text ::== (char | number)+
char ::== A | B | ... | Z | a | b | ... | z
number ::= 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
icon id ::= segment
----

.Example icon mapping file
[source]
----
# Business Service Topology
bsm.business-service = business_service <1>
bsm.ip-service = IP_service <2>
bsm.reduction-key = reduction_key <3>
----
<1> Icon definition for business services.
<2> Icon definition for IP services.
<3> Icon definition for reduction keys.

=== Icon resolution

The icon of a vertex is resolved as follows:

* If a `vertex ID`-to-`icon id` mapping is defined, the icon referenced by the `icon id` is used.
* If a mapping for the `icon key` determined by the topology provider for the vertex is defined, the icon referenced by the `icon id` is used.
** If no mapping exists and the `icon key` has more than one segment, reduce the `icon key` by the last segment and try resolving that `icon key`.
* If no mapping is defined, the fallback default `icon key` is used.

The following example icon mapping is defined for the Linkd Topology Provider:

[source, properties]
----
linkd.system.snmp.1.3.6.1.4.1.9.1.485 = server1
linkd.system.snmp.1.3.6 = server2
----

If the Enterprise OID of a node is `1.3.6.1.4.1.9.1.485` the icon with ID `server1` is used.
If the Enterprise OID of a node is `1.3.6` the icon with ID `server2` is used.
However, if the Enterprise OID of a node is `1.3.6.1.4.1.9.1.13` the icon with ID `server2` is used.

NOTE: The Linkd Topology Provider uses the Enterprise OID from each node to determine the icon of a vertex.

=== Change icon mappings

The easiest way to change an icon representation of an existing vertex is to use the Icon Selection Dialog in the Topology Map.
This will create a custom `icon key`-to-`icon id` mapping in the topology provider-specific icon mapping file.
In this case, the vertex ID is used as the `icon key`; this lets each vertex have its own icon.

If you prefer a more generic approach, you can modify the icon mapping file manually.

WARNING: Do not remove the default mappings or change the icon keys in the default mappings.

[[ga-topology-add-icons]]
=== Add new icons

All available icons are stored in `.svg` files located in `$\{OPENNMS_HOME}/jetty-webapps/opennms/svg`.
To add new icons, either add definitions to an existing `.svg` file, or create a new `.svg` file in that directory.

No matter how you add new icons to {page-component-title}, it's important that each new `icon id` describes a set of icons, rather than a single one.

.Example custom icon definition
[source,xml]
----
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg id="icons" xmlns="http://www.w3.org/2000/svg">
  <g id="my-custom_icon"> <1>
      <g id="my-custom_active"> <2>
          <!-- rect, path, circle, etc elements, supported by SVG -->
      </g>
      <g id="my-custom_rollover"> <3>
          <!-- rect, path, circle, etc elements, supported by SVG -->
      </g>
      <g id="my-custom"> <4>
          <!-- rect, path, circle, etc elements, supported by SVG -->
      </g>
  </g>
  <!-- Additional groups ... -->
</svg>
----
<1> Each icon must be in an SVG group with the ID `<icon id>_icon`.
Each SVG `<icon id>_icon` group must contain three subgroups with the IDs: `<icon id>_active`, `<icon id>_rollover`, and `<icon id>`.
<2> The icon to use when the vertex is selected.
<3> The icon to use when the vertex is moused over.
<4> The icon to use when the vertex visible, but not selected or moused over.

NOTE: It is important that each `icon id` is unique.
This means that there cannot be another `my-custom` ID in any other `.svg` file.

If the new icons should be selectable from the Topology Map's icon selection dialog, add an entry with the new `icon id` to `$\{OPENNMS_HOME}/etc/org.opennms.features.topology.app.icons.properties`.

.Snippet of `org.opennms.features.topology.app.icons.list`
[source, text]
----
access_gateway <1>
accesspoint
cloud
fileserver
linux_file_server
opennms_server
printer
router
workgroup_switch
my-custom <2>
----
<1> Already existing icon IDs.
<2> New icon ID.

NOTE: The order of entries in `org.opennms.features.topology.app.icons.list` determines the order in the icon selection dialog in the topology map.
