Custom Menu

A Custom Menu is a menu entry defined at space level. It links to an existing Custom HTML page or Animation, or acts as a group that holds child menus.

In the data model CustomMenu extends Menu, which means every custom menu is also a menu privilege. The two share a single UUID: custom_menu_id and menu_id are always the same value. This detail governs how visibility is configured.

Custom Menus belong to a space, not to a project. The relationship to a project is indirect, established through the project that owns the linked customHtmlId or animationId.

Fields

Field	Type	Required	Description
name	String (≤100)	Yes	Menu name. Cannot be changed after creation
contentType	Enum	Yes	Html, Animation or Group. Cannot be changed
icon	String (≤16384)	No	Icon descriptor JSON (see below)
menuOrder	Integer	No	Ordering within the menu
parent	CustomMenu	No	Parent menu — used for nesting
customHtmlId	String	Yes for Html	Custom HTML record to link. Cannot be changed
animationId	String	Yes for Animation	Animation record to link. Cannot be changed
animationParams	String (≤32767)	No	JSON parameters passed to the animation

The new-menu form asks for the common fields:

Immutable fields

name, contentType, customHtmlId and animationId are marked updatable = false in the database. A request that tries to change them does not fail — it returns HTTP 204, but the change is silently discarded.

The edit form does not lock these fields. You can type into the name box, pick a different content type and save; the interface gives no warning. The list continuing to show the old value afterwards is the expected behaviour, not a fault.

To rename a menu, change its type, or point it at a different HTML/Animation record, you must delete the menu and create it again. The only updatable fields are icon, menuOrder and animationParams.

Content Types

The ContentType enum has three values:

Type	Required field	Description
Html	customHtmlId	Opens an existing Custom HTML page. The same HTML can be linked from several menus
Animation	animationId	Opens an existing Animation. Parameters can be passed via animationParams
Group	—	An empty container that holds child menus

The form’s own list offers exactly these three:

There is no URL type

The content types do not include a URL option. To embed an external application, create a Custom HTML page of type Html and place an <iframe> inside it.

Icon

The Icon field on the menu form previews the selected icon. While none is set, Choose icon opens the library; once an icon is assigned the buttons become Change and Clear (the edit form pictured above shows that state).

The library offers four sources — FontAwesome, OpenBridge, Material Symbols and Custom — with search by name and a category filter.

The chosen icon is stored as a descriptor JSON made up of vector paths only; it carries no colour information. This lets the icon inherit the surrounding text colour and render correctly in both light and dark themes.

FontAwesome class names do not work

Class-name strings such as fas fa-chart-bar are silently rejected by the interface’s icon parser and the default icon is shown instead. The parser is deliberately strict: it returns null for any input it does not fully understand.

Support for uploaded bitmap icons has also been removed — the icon_file_id field from earlier versions no longer exists.

Menu Hierarchy

Custom Menus can be nested three levels deep at most. Each level has its own endpoint:

Attempting to create a fourth level returns an error. The same level-specific logic applies to updates and deletions.

A typical arrangement:

Each level has its own panel on screen. Selecting a root row lists that menu’s children in the second-level panel; selecting a row there in turn fills the third-level panel.

Html Menus

In JDK 21 a Custom HTML page is a separate record. The menu does not hold the content itself; it only references an existing HTML record. The order is:

1. Create the Custom HTML page → obtain its customHtmlId
2. Create a Custom Menu of type Html and pass that ID

At runtime the menu opens with the linked page embedded in it:

Reading data from the page

A Custom HTML page runs inside a sandboxed iframe. The only way to reach the inSCADA API is the InscadaApi proxy that the server injects into the page automatically:

var api = new InscadaApi();          // the page resolves its own project

(async function () {
  var v = await api.getVariableValue('ActivePower_kW');
  document.getElementById('power').textContent = v.value.toFixed(1);

  // Several variables — a single round trip
  var batch = await api.getVariableValues(['Voltage_V', 'Current_A']);
  console.log(batch.Voltage_V.value);
})();

Do not call the API with fetch

fetch('/api/variables/...') will not work. The request carries no authentication headers, and the content security policy blocks it in any case. All data access must go through InscadaApi.

Inline <script> blocks and inline event handlers such as onclick= written into the page’s HTML body are also blocked — the CSP only admits scripts the server has signed with a nonce. Put your JavaScript in the page’s separate JS field and attach events with addEventListener.

The sandboxed iframe also ignores alert(), confirm() and prompt() — use an in-page element for confirmation instead.

Menu Visibility

A new menu is bound to no role

Creating a Custom Menu also creates the menu privilege behind it, but binds it to no role at all — creating a menu writes no row to the role-menu table.

Who sees the menu depends on the kind of role the user holds:

• Holders of a system role (Administrator, Space Admin) see it immediately. For them visibility is not read from stored bindings; it is derived from every menu in the active space.
• Other roles — operator roles — cannot see the menu until a role-menu binding is added.

The practical consequence: you cannot confirm from an administrator account that operators can see the menu, because an administrator sees it with or without a binding. Verify with an account that holds the target operator role.

Older versions behaved differently

In earlier versions system roles were not exempt from this rule: a menu became visible only through a role-menu row, and since no such row can be written to a system role, an administrator had to create and assign a separate role merely to see a menu they had created themselves. That behaviour has changed — a system role now sees every menu in the active space.

A second change went the other way in the same period: the binding check used to be applied only in the interface, while the server returned the menu to everyone. It is now enforced server-side as well, so an operator without a binding cannot obtain the menu through the API either.

Adding it directly to the administrator role is not possible either: Administrator and Space Admin are system roles and cannot be modified; attempting to update them returns an error.

Because privileges are additive, the solution is to create a second role that carries only the relevant custom menus:

1. Create a role whose name reflects its purpose — for example PumpStationAccess
2. Add the new menu to that role
3. Assign the role to the relevant users — their existing roles are kept, the new one is added on top

For subsequent menus you only need to repeat step 2.

Assigning a role ends the user’s session

Assigning a role to a user, or removing one, immediately invalidates all of that user’s access and refresh tokens — the user has to sign in again.

Adding or removing menus on a role, and creating or deleting roles, do not affect tokens. So do the role assignment once, during setup, and afterwards only add menus to the role.

Following least privilege, add only custom menus to this role. System menus such as Home, Variables and Trends already come from the user’s administrator role; adding them again clutters the audit trail for no benefit.

Why can a user not see a menu?

1. List the user’s roles
2. List the menus bound to each of those roles
3. If the menu appears in none of them, the role-menu binding is missing

Cloning

An existing menu can be copied under a new name. Since name is immutable, this is the practical way to produce a similar menu with a different name.

Deletion

Deleting a Custom Menu also deletes the menu privilege behind it, and every role binding for that menu is cleaned up automatically. No dangling references are left on the roles.

Bulk deletion is level-specific: all the menus being deleted must sit at the same level (root / second / third). Use separate operations for menus at different levels.