Viz Mosart Web Applications

This page describes how to install, configure, and administer the Named Overlays Editor in a Viz Mosart deployment.

Prerequisites

Requirement	Details
Mosart Web Apps	The Named Overlays Editor is served by the Web Apps server and is included in the Mosart Web Apps installation package. The server must be installed and running.
Viz Mosart automation system	A running Mosart server is required. The editor reads and writes the named overlays on the Mosart server and shows in the toolbar whether it is connected to the main or the backup server.
Viz Pilot Edge (optional)	Required only if you want to import graphics from a Viz Pilot Data Server. Pilot Edge is a web plugin hosted by the Pilot Data Server.
Web browser	A modern web browser. The editor is a single-page application that runs entirely in the browser.

Accessing the Editor

Once the Web Apps server is running, the Named Overlays Editor is served at: https://<server-address>/namedoverlayseditor/

Replace <server-address> with the host name or IP address of the machine running the Web Apps server. The editor can also be opened from the App Launcher in the Mosart Web Apps Configuration Tool.

If authentication is enabled, you are redirected to a sign-in page before the editor opens. See Authentication and roles below.

Authentication and Roles

The editor recognises two roles. You assign them in your identity provider, not in the Configuration Tool, and the editor reads them from the roles claim in the user's token.

Role name	What the user can do
`mosart-admin`	Everything: view overlays, create, edit, delete, import and export them, update a graphic from the provider panel, and sync overlays to the backup server.
`mosart-viewer`	View the overlay list and overlay properties. No create, edit, delete, import, or sync. The editing controls are not shown.

Assign the roles before you enable authentication

A signed-in user who holds neither role does not get a read-only view. The editor shows an unauthorized-access screen and nothing else, because it fails closed. An identity provider with no Mosart roles configured therefore locks out everybody, which reads as a fault in the editor rather than as missing configuration. Assign a role to every user who needs the editor before you turn authentication on.

The roles must reach both tokens

Two layers check the user, and they read two different tokens:

Layer	Reads	Decides
Mosart Web Apps server	the ID token	whether the editor opens at all, and whether the editing controls are shown
Mosart server	the access token	whether the REST API accepts the request

This is the most common misconfiguration. If the roles are present in only the ID token, the editor looks completely correct and every save fails.

The claim must be flat, top-level, and named exactly roles. A nested claim, such as Keycloak's default realm_access.roles, is not read: the Web Apps server matches the claim name exactly.

Confirm that your provider emits the claim in both tokens. In Keycloak this means adding a protocol mapper for the roles and enabling it for the ID token and the access token separately. In Microsoft Entra ID, app roles that you have defined and assigned are emitted in a roles claim with no further claim mapping.

Where roles are enforced

Hiding the editing controls in the browser is not the whole protection. The Mosart server checks the role on every named overlays REST call, so a viewer cannot create, change, or delete an overlay by calling the API directly.

Info: Enforcement on the Mosart server requires Viz Mosart 5.16 or later with Mosart Web Apps 3.2 or later, and OIDC authentication enabled on the Mosart server itself, under Remote Controller Service > Security in the Mosart settings.

With authentication disabled, every user is treated as an administrator, no request is refused, and the roles have no effect.

Messages you may see

Message	What it means
The Mosart Server refused this operation for your user.	You are signed in, but your user does not hold the role this operation needs. Viewing needs `mosart-viewer` or `mosart-admin`, changing anything needs `mosart-admin`. Ask an administrator to assign the role in the identity provider. This is not a certificate or key problem.
The Mosart Server rejected the request as unauthenticated.	No valid credential reached the Mosart server. If you are signed in, your session has most likely expired: reload the page. Only when authentication is disabled does this point at the REST API key, which must match the key in the Configuration Tool. While OIDC authentication is on, the Mosart server ignores the REST API key entirely, so changing that key does not fix this.
No active Mosart Server.	Not a permissions problem. Automation must be running and on air on the main or the backup server before overlays can be loaded or saved.

Configuring the Viz Pilot Edge Plugin

The Pilot Edge plugin panel is configured in the Configuration Tool, on the Named Overlays Editor page of App Configuration:

In the Configuration Tool, open App Configuration and select Named Overlays Editor.
Select the checkbox for VIZ PILOT GRAPHICS AND ELEMENTS.
Provide values for:
- Application URL: where Viz Pilot Edge is running. Default: http://localhost:8177/app/pilotedge/pilotedge.html?mosid=pilot&sendbutton. Enter the host of your Viz Pilot Edge installation if it is not on the same machine.
- MOS Plugin ID: the MOS ID stamped on overlays created from this plugin. Default: PILOT.
Click Save.

Tip: The settings are stored in the NamedOverlaysEditor section of the Web Apps server configuration, under MosPlugins, with the plugin type pilot. Editing the file by hand is not required: the Configuration Tool writes it for you.

Info: The same Configuration Tool page also shows a VIZ FLOWICS GRAPHICS section. The Named Overlays Editor does not currently offer a Flowics panel, so those settings have no effect on this editor in this version.

Info: The plugin panel is optional. With no plugin configured, the editor still works for creating custom overlays and for XML import and export.

Main and Backup Servers

The toolbar shows whether the editor is working against the Main or the Backup Mosart server.

In a redundancy setup, named overlays live on both servers, and the two can drift apart if overlays are edited while one of them is unavailable. To align them, use Sync to backup server in the sidebar. It makes the backup server's overlays identical to the main server's: every overlay on the main server is copied across, replacing any overlay with the same slug, and overlays that exist only on the backup are removed. A confirmation dialog appears first, and a notification reports how many overlays were copied and removed.

Note: The Sync to backup server button is only shown to administrators, and only when the editor detects that a backup server is configured. In a single-server installation it does not appear at all.

The sync always reads from the main server and writes to the backup server explicitly, so it is safe to run during a failover: it will not copy the backup onto itself. Because it removes overlays that exist only on the backup, make sure the main server holds the set you want before running it.

Where overlays are stored

Overlays are stored on the Mosart server in NamedOverlayGraphics.xml, not in the browser and not on the Web Apps host. Any editor instance pointed at the same Mosart server sees the same overlay set, and the overlays are available to Mosart automation as soon as they are created. To keep a copy outside Mosart, use Export XML in the editor.

For background on named overlays and how Viz Mosart uses them, see Named Overlay Graphics in the Viz Mosart Administrator Guide. The editor links to it directly from Help in its help menu.

Troubleshooting

Symptom	What to check
The toolbar does not show a connected Mosart server	Check that the Mosart server is running and reachable, and that the server connection is correctly configured in the Configuration Tool under Server Configuration.
The overlay list stays empty on a server that has overlays	The editor cannot reach the Mosart server. Check the connection indicator in the toolbar and the server configuration.
The provider panel opens but stays empty	The plugin URL is not reachable from the browser. Open the URL directly in the same browser to confirm, and check that the Pilot Data Server is available.
Thumbnails are missing for Pilot Edge overlays	Thumbnails are resolved from the Pilot Data Server. Check that it is reachable from the browser.
Editing controls are missing	The signed-in user holds `mosart-viewer` rather than `mosart-admin`. See Authentication and roles above.
The editor shows an unauthorized-access screen instead of opening	The signed-in user holds neither `mosart-admin` nor `mosart-viewer`. Check that the role is assigned in the identity provider, and that it is spelled exactly as above: the earlier `namedoverlays-` names are no longer recognised.
The editor opens and looks correct, but every save is refused	The roles most likely reach the ID token but not the access token. The Mosart server reads the access token. See The roles must reach both tokens above.
Reads work but writes are refused for an administrator	Confirm the role name in the token is `mosart-admin`, and that the Mosart server was restarted after OIDC authentication was enabled. Every setting under Remote Controller Service > Security requires a restart of the Remote Control Service.
The Sync to backup server button is missing	It appears only for administrators, and only when a backup server is detected. Check the redundancy configuration for the Mosart server.

For general connectivity issues, see section Troubleshooting.