Topology Map

This section describes how to configure the topology map.

Properties

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

Property Description Type Default Value

Property	Description	Type	Default Value
showHeader	Defines if the Horizon 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

showHeader

Defines if the Horizon header is shown.

Boolean

true

autoRefresh.enabled

Enables auto-refresh.

Boolean

false

autoRefresh.interval

Defines the auto-refresh interval, in seconds.

Integer

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)

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

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

# 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:

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.

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.

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

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 Horizon, it’s important that each new icon id describes a set of icons, rather than a single one.

Example custom icon definition

<?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.

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

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.

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