fews-web-oc

Web OC Delft-FEWS configuration

Introduction

In order to connect Web OC to a FewsWebServices instance, some basic configuration is required in app-config.json. Please refer to: Web OC application configuration. All configuration related to what content is being displayed in Web OC, is managed by the Delft-FEWS configuration. For general documentation on this matter please refer to: Delft-FEWS Configuration Guide

Key files in the Delft-FEWS Configuration to get started with Web OC are:

Although Web OC will run without any further adjustments to the Delft-FEWS configuration, we strongly recommend you spend some time on your Topology configuration in relation to Web OC (see below).

System time

Please note that Web OC will always use the system time of the Web OC user’s device as Web OC system time. This time setting cannot be modified by Web OC configuration.

Web OC navigation using Topology

When we want to limit ourselves to a single menu/folder structure configured in Delft-FEWS for navigation in Web OC, it is logical to base this on Topology.xml. In Web OC, the entire Topology structure is displayed, to which the Web OC user has access via FewsWebServices.

For the general configuration of Topology.xml, please refer to: Topology Configuration.

Topology nodes in the Web OC component TopologyDisplay can be linked using Topology.xml as described below.

Link topology node to Back-end support Web OC Support Topology.xml config element
Data Analysis Display Yes Yes <dataAnalysisDisplayId>
Data download Yes Yes <dataDownloadDisplayId>
DisplayGroup Yes Yes <nodeId> (DisplayGroups.xml) or <displayGroupId> (Topology.xml)
Display Information Document Yes Yes <documentFile>
Document Displays Yes Yes <documentDisplayId>
Dynamic report Yes Yes <dynamicReportDisplayId>
Embedded Browser Yes Yes <embedUrl>
External url Yes Yes <url>
Filters Yes Yes <filterId>
Log Displays Yes Yes <logDisplayId>
Report Yes Yes <reportModuleInstanceId>
Run Task Yes Yes <workflowId> and <secondaryWorkflowId>
SchematicStatusDisplay Yes Yes <scadaDisplayId> and <scadaPanelId>
Spatial Display Yes Yes <gridDisplaySelection>
Web OC Dashboard Yes Yes <webOCDashboardId>

Data Analysis Display

Data Analysis Displays can be configured in the DataAnalysisDisplays.xml, part of the DisplayConfigFiles. One or more Data Analysis Displays can be configured and referenced in the Topology.xml using the <dataAnalysisDisplayId> element.

Please refer to the configuration documentation on how to configure the Data Analysis Displays documentation.


Data download

A data download display can be visualised in the WebOC by referencing a configured dataDownLoadDisplay Template through the <dataDownloadDisplayId> in combination with a <filterId>.


DisplayGroup

Web OC will show a time series graph and a drop-down menu for selection of displays within the configured displayGroup. Currently, two configuration options are supported by Web OC to link DisplayGroups to Topology nodes:

  1. Configure a <nodeId> element for a DisplayGroup in DisplayGroups.xml. No additional configuration is required in Topology.xml.
  2. Configure a <displayGroupId> element for a Topology node in Topology.xml.

The period shown in the graph corresponds to the configured relative view period in DisplayGroups.xml.

Changing the period in the time control updates the chart range and requested data, replacing any previous zoom selection. Ordinary data refreshes preserve the current zoom.

With the v5 chart engine, bar series sharing a subplot and value axis are stacked in their configured order. At each timestamp, missing or unreliable values are skipped without hiding bars from other series. Bars on different value axes are rendered separately.

Ensemble line requests use the v5 native ensemble plot to draw the returned members. Hovering identifies the nearest member and shows its value with the configured unit.

How plotWeight is interpreted in the WebOC

The WebOC uses CSS Flexbox to distribute the remaining vertical space proportionally over the subplots axis heights (excluding the legend and margin for tick labels). The flex-grow property specifies the grow rate of the container.

For WebOC, it is advised to use plotWeight values of 200 or higher. Since plotWeight is also used as the minimum axis height (in pixels, excluding legend/brush and margins), this helps keep subplots readable on small (mobile) screens. If a subplot should be two times larger than another subplot, set its plotWeight to 400.

When no plotWeight is specified, all subplots will have an equal height of 400px including the legend and tick labels. On desktop resolutions, typically two subplots will fit on screen, while a third subplot requires a scrollbar.


Display Information Document

A static document (typically HTML format) can be linked to a topology node. In order to link a document to a topology node, the element <documentFile> in Topology.xml has to be configured at topology node level. The document itself should be part of the FEWS configuration (Config/WebResourcesFiles). The content of the document will be visualised under the “More Info” section in the side panel.


Document Displays

Document Displays as configured in the DisplayConfigFiles folder of the Delft-FEWS Config are available in the WebOC. One or more displays can be configured in the DocumentDisplays.xml. There are three different types of document displays:

  1. Report display: Visualise and edit reports based on
    • reportModuleInstanceId or
    • archiveProductId
  2. Document Browser: Browse and visualise products in the Archive.
  3. Compose display: Produce on the fly a new archiveProduct based on a template. Please note that the compose display is not availble yet.

For more information about the configuration of the Document Displays refer to the Document Display configuration documentation.


Dynamic report

The dynamic report module provides the ability to dynamically generate a report based on a template configured in FEWS. This typically involves time- and/or location-dependent data displayed in tabular format. See: Dynamic Report Displays.

The dynamic report can be linked to the topology using <dynamicReportDisplayId> in Topology.xml. Web OC displays a time slider to request the report for the selected time. When <selectedLocationVariable> is configured in DynamicReportDisplays.xml, a location selection menu also becomes available.

The report view, including a dynamic report in a time series window, can be edited temporarily, and node map screenshots can be added to the edited report. Chart capture is currently disabled; screenshots contain only the map and its colour legend. Choose a map aspect ratio: 16:9 (the default), 4:3, 1:1, or 3:4. The preview resizes before capture; the map is not stretched or cropped afterward. The aspect ratio selector is left of the size selector; size labels update to show width × height when the ratio changes. The dialog uses nearly the full viewport height and becomes fullscreen at the application’s mobile breakpoint. The map preview is centered and constrained to the available dialog space, including portrait aspect ratios. Choose an output width of 640 pixels (small), 1280 pixels (medium), or 1920 pixels (large, the default). The aspect ratio is preserved and height follows the map aspect ratio. The output always uses the selected width; smaller map sources are enlarged without adding detail. Screenshots are embedded as PNG data URLs, with a limit of 20 screenshots and 5 MiB of encoded screenshot data per report. Editing uses TipTap and may change HTML or formatting that its extensions do not support. In particular, TipTap currently rewrites table sections such as <thead> and <tbody>. Styles that depend on those sections may therefore change while editing or after previewing an edited report. The capture includes the map’s colour legend (categorical or gradient). The capture dialog explains how to select a node and adjust the map. Wait for the map and colour legend to load before capturing. Each screenshot has an editable caption containing the node name, the source data layer ID and its valid time in UTC. The caption is included in HTML and print/PDF exports. The embedded PNG retains its captured pixel resolution. Screenshots shrink to fit the report width without stretching or enlarging smaller images, including in saved HTML and print/PDF. For print, aim for approximately 300 effective DPI: 1920 pixels at 17 cm wide is about 287 DPI. Actual DPI depends on capture resolution and printed width; enlarging a smaller source does not improve detail.

Edits and screenshots are not saved to FEWS and are discarded when the report, location, or time changes. In both the report view and the time series report panel, use Save as HTML or Print or save as PDF to save the current report, including local edits and screenshots, as HTML or through the browser print dialog as PDF. These export options respect the report download setting. In a time series window, choose Export and edit report… from the dot menu to open the report and replace the window toolbar with editing and export controls. Close report export to restore the normal window toolbar and display the original report without local edits. Local edits are retained for reopening export mode until the report changes. Export mode fills the application’s main content area, leaving the application header and navigation visible. Closing it restores the original time series window size. The information icon in the export toolbar explains the local-only changes and editor formatting limitations in a tooltip. The primary Edit/Apply edits button is first in the export toolbar. Apply edits leaves the editor and displays the locally edited report; it does not save changes to FEWS. Save as HTML and Print or save as PDF are separate buttons with icons. Printing opens the current report in a new browser tab and opens the print dialog after its styles, images and fonts load. Allow popups for this site. The tab remains open after printing or cancelling the dialog. The print tab contains only the report, without application layout constraints. Print CSS allows the report to flow across pages and uses page margin boxes for the document title and “Page n out of m” footer, without adding report elements. Print margins are zero on the left and right, with 20 mm at the top and bottom. The first page has no top margin or document-title header. CSS page headers and footers require a browser supporting page margin boxes (current Chrome/Edge). Disable the browser’s own headers and footers to avoid duplicates. For dynamic page-header values in Chrome/Edge, generate literal CSS content in the FEWS report template; these browsers do not support CSS named strings (string-set and string()). The first-page margin is controlled by the report’s own @page :first rule. While editing, a separate floating formatting toolbar above the report provides undo/redo, bold, italic, underline, highlighting, text color, and alignment.

Read-only report sections

Add data-readonly="true" to a supported report block element to keep that section fixed while allowing edits elsewhere:

<div data-readonly="true">
  <h2>Fixed report information</h2>
  <p>This forecast must remain unchanged.</p>
</div>
<p>Editable commentary</p>

Use a div wrapper for a section, or mark an existing supported block such as a paragraph, heading, header, article, table, row, or cell. Ordinary inline spans are not supported as read-only sections; wrap their paragraph instead. Only the exact value "true" enables protection. A nested data-readonly="false" does not unlock content inside a protected section.

In the editor, protected sections cannot be edited, deleted, moved, or reformatted. Operations whose selection spans protected content are rejected as a whole, including paste or deletion; edit the surrounding content separately. Time series input values inside protected sections remain plain text, both in the editor and in the report view. The marker is retained in preview and saved HTML, so protection also applies when reopening locally edited content. An ordinary contenteditable="false" attribute is not a substitute for this marker. This is an editor restriction, not server-side validation or protection against changing an exported HTML file outside Web OC.

Initial editor caret

Add a numeric data-editor-caret attribute to a supported report block to choose where typing starts when opening the editor:

<p>Report introduction</p>
<p data-editor-caret="0">Write commentary here.</p>
<p data-editor-caret="1">Additional notes.</p>

The editor focuses the start of the first editable text block in the marked section and scrolls the caret into view. A marker on a wrapper such as a div or table targets its first editable paragraph or heading. Empty paragraphs are valid targets. Inline spans and elements without an editable text block are not caret targets.

The lowest non-negative integer wins (0 before 1, then 2, etc.), with document order breaking ties. Negative values are excluded from marker selection, like a negative tabindex; invalid values (including "true") are ignored. Unlike tabindex, this attribute only controls initial caret placement and does not change keyboard Tab navigation. Markers in read-only sections are skipped, including those inside a read-only ancestor. Without a usable marker, the first editable text block is used. If no editable text block exists, the editor is not focused.

This placement applies each time editing starts, including when reopening local edits. The marker survives preview and HTML export. Positioning the caret does not change report content or add a placeholder.

Styling a dynamic report

Style the report template with CSS classes. Put the CSS rules in a <style> element in the template, or in a style sheet in the FEWS static resources (WebResourceFiles) that is linked with a relative path:

<head>
  <link rel="stylesheet" href="css/DynamicReport.css" />
  <style>
    .number {
      text-align: right;
    }
  </style>
</head>
<body>
  <table class="document-file-table">
    <tr>
      <td>Intake Plant A</td>
      <td class="number">-0.699</td>
    </tr>
  </table>
</body>

Do not use inline style attributes, such as <td style="text-align: right">. Some browsers block them when the Content Security Policy does not allow 'unsafe-inline' in style-src. Classes work with any style-src. Style sheets that are not in the FEWS static resources, such as absolute URLs to other servers, are ignored.

The report styles only apply to the report, they do not affect the rest of the Web OC.

When a report is edited, Tiptap converts table rows to a single <tbody> and does not preserve <thead>. To keep header cells styled in the editor and in edited exports, target th directly instead of relying on thead th selectors.

Web OC and isolated styling

A report is shown with one of two stylings:

Isolated styling is the default. To opt in to Web OC styling, add a <meta> element in the <head> of the template:

<head>
  <meta name="fews-dynamic-report-styling" content="weboc" />
</head>

In the report styles, :scope is the element that contains the report, and the Web OC adds the dark class to an element around it in dark mode. This works in both stylings. Use it to set the colours of the report, for example with CSS variables:

Use :scope instead of :root for report-level variables. :root targets the document root, not the embedded report, so its variables are unavailable inside the report scope and colours using them will not render. :scope also works when the report is opened as a standalone HTML document.

:scope {
  --report-text: rgb(33, 33, 33);
  --report-surface: rgb(255, 255, 255);
  color: var(--report-text);
  background-color: var(--report-surface);
  font: 14px/1.5 system-ui, sans-serif;
}

.dark :scope {
  --report-text: rgb(255, 255, 255);
  --report-surface: rgb(33, 33, 33);
}

With Web OC styling the report can also use the theme colours of the Web OC, such as rgb(var(--v-theme-primary)) and rgb(var(--v-theme-surface)). These follow the Web OC theme, dark mode and the customStyleSheet automatically.


Embedded Browser

When a <embedUrl> element is configured in the selected topology node, Web OC will open an embedded browser window for the URL configured. Please note that Content Security Policy must be configured correctly to allow embedding.


External url

When a <url> element is configured in the selected topology node, Web OC will open a new browser window (outside Web OC) for the URL configured.

[!NOTE] This is only supported for topology nodes with only the <url> element configured.


Filters

Web OC will show a map, displaying all locations configured in the filterId linked to the selected topology node. Locations are also listed in a drop-down menu. Use the <filterId> item in Topology.xml to configure a filterId.

By selecting a location on the map (hold Ctrl key for multi-select) or from the list, time series graphs will be displayed for all parameters configured in Filters.xml for the linked filterId. Time series graphs are grouped by parameterGroup. The period shown in the graph corresponds to the configured relative view period (relative to Web OC system time) of the time series in the Filters.xml.

When locations are shown on the Web OC map, icons are used as configured in Delft-FEWS. Icon overlays for threshold crossings are also shown consistently with the Delft-FEWS Desktop OC.

See Thresholds documentation. Information on threshold crossings for the configured filter will be visualised when

<showActiveThresholdCrossingsForFilters>true</showActiveThresholdCrossingsForFilters>

is configured in WebOperatorClient.xml. If configured the following threshold information will be made available:

  1. An indicator for the number of locations with threshold crossings per topology node will be shown in the topology navigation panel on the left-side of the GUI.
  2. A threshold icon in the topbar. The icon is greyed out when no threshold crossings are active for the configured filter. If there are threshold crossings, then the icon will have the color of the most severe threshold color.
  3. A threshold panel, accessible by clicking on the threshold icon in the topbar. The panel shows an overview with the thresholdcrossings, sorted by location. In addition location on the map can be filtered by clicking on the threshold summary icons.

Handling of parent and child locations

The Web OC handles parent and child locations similar to the data viewer and map component in the Operator Client. In summary:

  1. Location icons & zoomlevel: parent locations are always visible on the map. child locations appear dynamically depending on the zoomlevel and the available space on the map.
  2. Threshold icons: parents that have child locations with an exceeded threshold inherit the most severe child threshold icon.
  3. Location selection on the map: when a parent location is selected, automatically all childs are selected as well. Childs can be deselected through the location search menu.
  4. The location search menu: in the location menu parents and their childs are grouped together, similar to the data viewer. By expanding the parent child locations can be selected or deselected.

Log Displays

Log Displays as configured in the DisplayConfigFiles folder of the Delft-FEWS Config. One or more log displays can be configured and referenced in the Topology.xml using the <logDisplayId> element. For more information about the configuration of the Log Displays refer to the configuration documentation.


Report

Reports generated by the FEWS Report Module can be made available for display in Web OC. In order to link a report to a topology node, the element <reportModuleInstanceId> in Topology.xml has be configured at topology node level. Only reports that are stored in the FEWS database can be displayed in Web OC (<sendToLocalFileSystem> = false in report module configuration).


Run Task

It is possible to submit a task to the Delft-FEWS back-end by configuring a <workflowId> or <secondaryWorkflowId> in Topology.xml. At the moment only workFlows with a whatIfTemplateId (workFlowDescriptors.xml) can be submitted. You have to explicitly allow tasks to run from Web OC by configuring <runTask enabled="true"/> in WebOperatorClient.xml (default is false). When correctly configured, a “Run Task” option will appear in the Web OC side panel.

Support for what-if scenarios

What-if templates consist of what-if properties and modifiers. Currently only what-if properties are supported in the Web OC.

Pre-defined properties

Pre-defined properties are xMin, xMax, yMin, yMax, xCellSize, and yCellSize. When these properties are configured in the whatIfTemplate, Web OC will provide users with the option to draw a bounding box on the map. The task will be submitted using the processdata endpoint instead of POST run task.

The purpose of the processdata endpoint is to download data based on the xMin, xMax, yMin, yMax, xCellSize, and yCellSize properties provided by the user. A pre-defined property FILE_NAME can be configured in WorkflowDescriptors.xml to set the name of the file to be downloaded. The file name will then be yyyyMMddTHHmmssFILE_NAME.

Other pre-defined properties are latitude and longitude. When these properties are configured in the whatIfTemplate, Web OC will provide users with the option to draw a point on the map. Coordinates of the point selected will be submitted to the back-end when running the scenario.

Run task panel in a dashboard

Instead of running a task from the web oc side panel its also possible to add the run task option to a web oc dashboard. See Web OC Dashboards


SchematicStatusDisplay

(no description provided yet — add details here if needed, e.g., how <scadaDisplayId> and <scadaPanelId> are configured)


Spatial Display

Web OC will show a map, displaying the configured plotId linked to the selected topology node. Use the <gridDisplaySelection> item in Topology.xml to configure a plotId. A time slider will show up for navigation in time. The period covered by the time slider is based on the configured relative view period of the time series in the GridDisplay.xml with reference to the system time of Web OC (system time of user’s device).

The classbreaks (legend) on the Spatial Display is only shown in the Web-OC when the Spatial Display plotId uses classbreaks from the TimeSeriesDisplayConfig.xml. Examples are provided on the Delft-FEWS WIKI pages: Time Series Display Configuration and Grid Display Configuration. It is possible to configure multiple classBreaks for a single gridPlot. Web OC will allow users to switch between them.

Optionally, gridded vector data can be shown as an animated layer in Web OC by configuring the <animatedVectors> settings in Spatial Display.

In Topology.xml, the desired mapExtentId should be configured on the topologyNode through the <mapExtentId>myExtent</mapExtentId> element.

Web OC Dashboards

In Topology.xml, a dashboard is linked to a node using <webOCDashboardId>.
For further configuration, see: WebOCDashboards.xml.

The desired mapExtentId should be configured on the topologyNode, through the Example element.


Threshold Information in WebOC

In WebOC, the following options exist for displaying threshold information:

  1. Icons on the map
    For this feature, a filterId must be linked to a topology node.
    Location overlay icons are displayed on the map, consistent with the Desktop OC.

  2. Count on topology tree
    Indicates the number of threshold crossings by means of a “count” per topology node.
    A filterId must be linked to a topology node for this to work.
    When this is the case, the topology tree shows the number of locations for which threshold exceedances exist.
    This option is only visible if
    <showActiveThresholdCrossingsForFilters>true</showActiveThresholdCrossingsForFilters>

  3. Thresholds overview Indicates the number of threshold crossings by means of a “count” per topology node.
    A filterId must be linked to a topology node for this to work.
    When this is the case, the top bar displays a count of the number of locations for which threshold exceedances exist.
    By double-clicking, the threshold overview becomes visible in a side panel.
    This option is only visible if
    <showActiveThresholdCrossingsForFilters>true</showActiveThresholdCrossingsForFilters>

Web OC side panel

Web OC includes a side panel that can be opened via the kebab menu (three vertical dots) in the top-right corner of the screen.
Depending on the configuration, the following information may be visible:

Permissions

By assigning viewPermissions in Topology.xml, it is possible to configure nodes for Web OC users that do not affect usage in the “thick” client. If authentication is not used for Web OC, permissions can still be utilized by configuring “defaultUser” in WebServices.xml. The Web OC component that utilizes Topology.xml is TopologyDisplay.

Other WEB OC functional components

Next to the Topology Display, three additional components can be configured in WebOperatorClient.xml: spatialDisplay, systemMonitor and schematicStatusDisplay.

spatialDisplay: A tree view will list all gridPlots (configured permissions respected) from the Spatial Display. Selected dataLayer will be displayed on the map.

systemMonitor: “Import status” and “Running Tasks” components of system monitor will be displayed in Web OC side panel. The System Monitor as seperate component will be phased out.

schematicStatusDisplay: A tree view will list all SSD displayGroups including all displayPanels (configured permissions respected) available to FewsWebServices. Most click-actions on displayPanels are supported, see SSD Service documentation.

HTML display: Component, only available in Web OC, to either show static HTML pages stored in the FEWS Configuration (WebResourceFiles) or external web pages. Multiple HTML displays can be configured with distinct paths, including when the backend returns the same component ID for each. Use the paths in the help menu to open the corresponding pages. A default component is selected by ID, so repeated IDs cannot uniquely identify a default HTML display; the last matching display is used. See WebOperatorClient.xml configuration.

Help menu: Drop-down menu available on the bottom left side of Web OC. See WebOperatorClient.xml configuration.

User settings

Web OC users can change their settings, such as theme, units and map options, via the cog icon in the top-right corner of the screen. All settings opens the full list. Restore defaults resets every setting to the defaults described below.

Default user settings

The defaults for all users can be configured in WebResourceFiles/default-user-settings.json. For each setting, the configuration can:

Example:

{
  "$schema": "./default-user-settings.schema.json",
  "settings": [
    { "id": "ui.theme", "value": "dark" },
    { "id": "units.displayUnits", "value": "system", "favorite": true },
    { "id": "ui.locale", "value": "default", "enabled": true },
    { "id": "charts.brush", "value": false, "enabled": false },
    {
      "id": "ui.timeZone",
      "value": "UTC",
      "items": [
        { "value": "UTC" },
        { "value": "Europe/Amsterdam", "title": "Amsterdam" }
      ]
    }
  ]
}

Each entry has the following properties. Only id is required.

Property Description
id Id of the setting, see the table below.
value Default value of the setting.
enabled true shows the setting to users. false hides it, and the configured value (or the Web OC default) applies to all users; values users chose earlier are ignored while the setting is hidden. When omitted, the Web OC default is used: all settings are shown, except the language selection.
favorite true shows the setting in the user settings menu (cog icon). Users can change this themselves.
items Options users can choose from, replacing the built-in options. Only for settings with a list of values, except ui.map.theme. Each option has a value and optionally a title, an icon (Material Design icon, e.g. mdi-earth) and an abbreviation shown instead of an icon. Without a title or icon, those of the built-in option with the same value are used, or else the value itself. A configured title is shown as is in every language, instead of the translation of the built-in title. The value of the setting must be one of the options; when omitted and the built-in default is not one of them, the first option is the default.

A value chosen by a user takes precedence over the configured default. Web OC only stores the settings users changed themselves, so a change of a default in the configuration reaches all users who did not change that setting.

Available settings:

Group Id Setting Values Web OC default
Units units.displayUnits Unit System system, display display
Datum datum.verticalDatum Absolute vertical datum true, false true
UI ui.theme Theme auto, light, dark auto
UI ui.locale Language system, default, en, de default (hidden)
UI ui.timeZone Time zone system, UTC or an IANA time zone system
UI ui.hierarchical-menu-style Menu style auto, tree, column auto
UI ui.sidebar-style Sidebar style minimal, full labels full labels
UI ui.scale UI scale 0.8, 0.85, 0.9, 0.95, 1, 1.1, 1.2 1
Map ui.map.theme Basemap automatic, light, dark or a base map id automatic
Map ui.map.showLocationNames Show location names true, false true
Map ui.map.showDataAvailability Show data availability true, false false
Map ui.map.navigationControl Show navigation control true, false false
Map ui.map.geolocationControl Show your location true, false false
Map ui.map.measuringTools Show measuring tools true, false false
Map ui.map.data-download-tools Show map data download tools true, false false
Map ui.map.showCoordinates Show mouse coordinates true, false false
Charts charts.scrollZoomMode Scroll wheel zoom mode off, x, y, xy x
Charts charts.brush Show brush chart true, false false

For ui.locale, default is the language set by VITE_I18N_LOCALE in the application configuration, and system is the language of the user’s browser or operating system, if Web OC supports it.

For ui.timeZone, system is the time zone of the user’s browser or operating system. Other values are IANA time zone names, such as UTC or Europe/Amsterdam. Configure items to offer other time zones than system and UTC. Unknown time zones are ignored.

Time zones

Users choose the time zone in the user settings and in the time control menu, which shows the UTC offset of each option. To offer additional time zones, configure the options of ui.timeZone with items. The options replace the built-in ones, so include system and UTC to keep them.

For example, for a system in Australia, with Sydney time as default and the time zone in the favorites of the user settings menu:

{
  "$schema": "./default-user-settings.schema.json",
  "settings": [
    {
      "id": "ui.timeZone",
      "value": "Australia/Sydney",
      "favorite": true,
      "items": [
        { "value": "system" },
        { "value": "UTC" },
        { "value": "Australia/Perth", "title": "Perth (AWST)" },
        { "value": "Australia/Darwin", "title": "Darwin (ACST)" },
        { "value": "Australia/Adelaide", "title": "Adelaide (ACST/ACDT)" },
        { "value": "Australia/Brisbane", "title": "Brisbane (AEST)" },
        { "value": "Australia/Sydney", "title": "Sydney, Canberra, Melbourne (AEST/AEDT)" },
        { "value": "Australia/Hobart", "title": "Hobart (AEST/AEDT)" }
      ]
    }
  ]
}

Use a time zone name, not a fixed offset such as +10:00: daylight saving time follows from the name. Adelaide, Sydney and Hobart change to daylight saving time in summer, while Perth, Darwin and Brisbane keep the same offset all year. Without a title, the time zone name is shown, e.g. Australia/Perth.

JSON schema

The JSON schema for default-user-settings.json describes all settings and their allowed values. Download it to WebResourceFiles/default-user-settings.schema.json and refer to it with "$schema": "./default-user-settings.schema.json", as in the example above. Editors like Visual Studio Code then validate the file, suggest setting ids and values, and show their descriptions. Use the schema that belongs to the Web OC version you deploy, as new versions can add settings.

Web OC ignores invalid entries, such as an unknown id or a value that is not allowed, and lists them as a warning in the browser console (developer tools).

Translations

Web OC includes translations in English and German. Texts, including the names of user settings and their options, can be changed or translated per language in WebResourceFiles/locales/<language code>.json, for example locales/en.json and locales/de.json. Only the texts in the file are replaced; all other texts keep the Web OC translation. Include only the texts you want to change, so that you keep receiving improvements of the other texts with new Web OC versions.

Names of settings, options and groups are found under userSettings:

Example locales/de.json:

{
  "userSettings": {
    "groups": {
      "UI": "Benutzeroberfläche"
    },
    "items": {
      "charts": {
        "brush": {
          "label": "Übersichtsdiagramm anzeigen"
        }
      }
    }
  }
}

Web OC loads the file of the language in use. Files that cannot be read are listed as a warning in the browser console.

Known issues