Menu Templates

The menu organization is configured by the use of JSON menu templates. Currently these can be found in the opennms/jetty-webapps/opennms/WEB-INF folder in your Horizon installation. Eventually these will be moved to the opennms/etc folder.

The menu-template.json file controls the menu configuration. It is read by the Rest API v2 Menu service and displayed by the UI. Configuration changes made in the file will take effect as soon as the browser page is refreshed (no need to restart Horizon).

Currently there are 3 menu templates:

  • menu-template-default.json: This is the default template (the same as the menu-template.json that is installed by default) and represents our latest recommended design.

  • menu-template-alt.json is an alternative configuration.

  • menu-template-legacy.json organizes the menu similar to previous versions of Horizon.

To use any of these menus, simply copy one of them to menu-template.json.

If you wish to create your own configuration, we recommend creating a new file, then copying it to menu-template.json.

Template structure

The menu template structure can be found in the Java code in: org.opennms.web.rest.support.menu.model.MainMenu and org.opennms.web.rest.support.menu.model.MenuEntry.

Item Description

templateName

A name for the template.

baseHref, homeUrl, formattedDateTime, formattedDate, formattedTime, noticeStatus, username, baseNodeUrl, zenithConnectEnabled, zenithConnectBaseUrl, zenithConnectRelativeUrl, copyrightDates, version

These are filled in at runtime with values. Any values you enter will be ignored.

displayAddNodeButton

Whether to display the "Add A Node" button on the top menu.

sideMenuInitialExpand

Whether the side menu is initially expanded.

userTileProviders

Tile provider information for the Geographical Map. We strongly suggest using the values provided in the existing templates.

helpMenu, selfServiceMenu, userNotificationMenu, provisionMenu, flowsMenu, configurationMenu

Control some specific menus. Most of these are deprecated and may be removed in a future version, we suggest not editing them.

menus

An array of top level menus, containing menu items. This is the place to configure what is displayed in the side menu, see the table below.

Top level menu item configuration

Within the menus array, each item is a top-level menu item for the side menu.

Item Description

id

A unique id for the top-level menu item. These are used in the HTML markup so we recommend using only something suitable for an HTML element id. For top-level items, the convention is to have a suffix of Menu, e.g. administrationMenu, operationsMenu, etc.

name

The name of the top-level menu item which is displayed in the menu UI.

url

The URL that the top-level menu links to. Generally this is "#" since the actual links are in the menu items. This will be used in the future to link directly from a top-level menu item (in which case it should not have any items).

locationMatch

Used by the Search feature.

icon

An icon path ID for the icon to display. These must be Feather icons, see https://feather.nanthealth.com/Components/Icon/ for a list. For example "action/AccountCircle". Note that currently only some of these icons are actually available to be used in the menu templates. You can use any icons that are currently used in the provided menu template files, and more will be added in the future. Currently icons are only available for the top-level menu items.

roles

An array of roles that the user must have in order to see the menu item. If this is null or [], then the menu item is always displayed. The roles match those found in user configuration. If roles are specified, the user needs to have at least one of the given roles. Example: to restrict the menu item to be seen only by administrators, specify "roles": ["ROLE_ADMIN"]. Note that roles is usually specified on the menu item rather than on the top-level menu item.

items

An array of individual menu items, see the table below.

type

The type of the top-level menu item. The default is item; you can just omit this type field if this is a normal menu item. The other option is separator which will draw a horizontal separator line, useful for grouping the menu items. We may add header in the future to display a text header which isn’t a menu item.

The items under each top level menu contain the individual menu items.

Item Description

id

A unique ID for the menu item.

name

The display name for the menu item.

url

The url that the menu item links to. If it is non-external, should be a relative link under the main /opennms path. Example: "url": "element/index.jsp" to link to the Search Inventory page. If it is an external link, provide the entire absolute URL, e.g. "url": "https://www.opennms.com".

locationMatch

See above.

roles

See above. Set to null if the item should always be displayed regardless of the user’s role.

isExternalLink

If true, then the url is treated as an external, absolute link. This is optional and can be omitted.

linkTarget

If present, specifies a target for the link, like the HTML target attribute. Currently only _blank and _self are supported; _self is the default so does not need to be specified. This is optional and can be omitted.

icon

See above. However, currently this is only supported for the top-level menu items.

requiredSystemProperties

This is an array of name/value pairs, where the name is a property name in an OpenNMS properties file (e.g. /etc/opennms.properties or etc/opennms.properties.d/*.properties) and the value is the value it needs to be in order to display the menu item. See below for an example.

action

Used for performing some special actions when the item is clicked, rather than navigating to a link. Currently the only action is logout which will log out the user. Generally this is omitted and url is used instead.

Here the requiredSystemProperties is used to display this menu item only if opennms.zenithConnect.enabled=true is found in a .properties file.

Example of requiredSystemProperties:
{
  "id": "zenithConnect",
  "name": "Zenith Connect",
  // other properties...
  "requiredSystemProperties": [
    {
      "name": "opennms.zenithConnect.enabled",
      "value": "true"
    }
  ]
}