Generic penalty box documentation

solutions/custom_solutions/Generic_Penalty_Box/Generic_Penalty_Box_Installation.md

@@ -0,0 +1,29 @@
+---
+uid: Generic_Penalty_Box_Installation
+---
+
+# Installing the Generic Penalty Box
+
+## Deploying the Generic Penalty Box
+
+1. Deploy the Generic Penalty Box solution from the Catalog.
+
+1. When the deployment is complete, go to the folder `C:\Skyline DataMiner\Webpages\Public\generic-penalty-box` on the DataMiner Agent.
+
+1. Edit *generic-penalty-box/config.json* to match your environment (protocol name, parameter IDs, etc.).
+
+   > [!TIP]
+   > For details, see [Configuring the Generic Penalty Box](xref:Generic_Penalty_Box_Configuration).
+
+1. Browse to `http://[DMA name]/public/generic-penalty-box/` in a web browser.
+
+> [!NOTE]
+> *config.json* is loaded fresh on every page load, so any edits you make take effect immediately on the next browser refresh. No rebuild is required.
+
+## Creating additional penalty boxes
+
+It is possible to display multiple penalty box walls on the same DataMiner Agent, each with its own configuration, for example, one per connector or one per site.
+
+To do this, copy the deployed *generic-penalty-box* folder in `C:\Skyline DataMiner\Webpages\Public` and rename the copy, for example to *generic-penalty-box-eaton-ups*.
+
+You can then configure each copy independently by editing its own [*config.json*](xref:Generic_Penalty_Box_Configuration), and you can access the copies using the folder name, for example, `http://[DMA name]/public/generic-penalty-box-eaton-ups/`.

solutions/custom_solutions/Generic_Penalty_Box/Generic_Penalty_Box_Overview.md

@@ -0,0 +1,14 @@
+---
+uid: Generic_Penalty_Box_Overview
+---
+
+# Generic Penalty Box
+
+A **penalty box** is an exception-only monitoring view used in broadcast Master Control Rooms (MCRs) and IT/Network Operations Centers (NOCs). Unlike a dashboard that shows the full inventory of monitored items, a penalty box shows **only the items currently in an error, degraded, or alarm state**, and keeps them visible until the issue is acknowledged or resolved.
+
+Generic Penalty Box is a DataMiner application that puts a live wall display of active alarms in front of your team. It watches every element of a connector you choose and shows only the elements currently in alarm. These are presented as easy-to-scan cards ordered by severity, so the most urgent issues stand out first. The wall updates itself automatically as alarms change, and the entire look and feel, including what is shown, how it is organized, and how it is branded, can be adjusted after deployment without rebuilding the app.
+
+> [!IMPORTANT]
+> After deploying the Generic Penalty Box solution, you must edit [*config.json*](xref:Generic_Penalty_Box_Configuration) to match your environment before the app can be used. See [Installing the Generic Penalty Box](xref:Generic_Penalty_Box_Installation).
+
+![Generic Penalty Box wall](~/solutions/images/Generic_Penalty_Box_No_Grouping.png)

solutions/custom_solutions/Generic_Penalty_Box/Generic_Penalty_Box_Use.md

@@ -0,0 +1,86 @@
+---
+uid: Generic_Penalty_Box_Usage
+---
+
+# Using the Generic Penalty Box
+
+## Grouping
+
+In the upper-right corner of the app UI, you can find the *Grouping* dropdown bx. You can use this to switch between the different modes defined for the app (using the [`groupingOptions`](xref:Generic_Penalty_Box_Configuration#groupingoptions) in the configuration file):
+
+- **Tier-based**: elements are placed into named buckets by matching their value against the configured tiers. Groups appear in the same order the tiers are listed (the first one listed shows first). Elements that match no tier collect in an "Uncategorized" bucket.
+- **Dynamic**: groups form automatically from the distinct values that exist in live data. This is useful for properties like *region* or *location*, where the set of values is not fixed in advance. New values appear as new group headers automatically.
+- **No grouping**: a flat grid sorted by severity and alarm recency.
+
+The active grouping is remembered per browser.
+
+![No grouping, flat list](~/solutions/images/Generic_Penalty_Box_No_Grouping.png)
+
+![Grouped by service tier](~/solutions/images/Generic_Penalty_Box_Grouped_By_Tier.png)
+
+![Grouped by region](~/solutions/images/Generic_Penalty_Box_Grouped_By_Region.png)
+
+## Detail view
+
+Click any card to open the detail overlay:
+
+- **Header**: severity indicator, element name, and criticality tier label.
+- **Config-driven panels**: each entry from [`detailPanels`](xref:Generic_Penalty_Box_Configuration#detailpanels) rendered as a labeled key/value grid.
+- **Active alarms**: a full list showing severity, parameter name, display value, and timestamp.
+- **Properties**: the element's DataMiner custom properties, as configured in [`elementProperties`](xref:Generic_Penalty_Box_Configuration#elementproperties).
+- **Monitoring link**: when [`monitoring.enabled`](xref:Generic_Penalty_Box_Configuration#monitoring) is `true`, a button links to DataMiner Monitoring.
+
+![Detail overlay](~/solutions/images/Generic_Penalty_Box_Detail_View.png)
+
+## Real-time push
+
+When [`realtime.enabled`](xref:Generic_Penalty_Box_Configuration#realtime) is `true`, the app opens one WebSocket session per monitored element using the *Generic Parameter Webhook* GQI data source. Parameter value changes arrive within seconds and update card fields immediately, without waiting for the next poll. A separate alarm-page subscription updates severity and alarm counts.
+
+On a WebSocket disconnect, the app reconnects automatically after the configured `reconnectMs` interval. The *Live*/*Offline* indicator in the header reflects the push state at all times.
+
+## Severity filter
+
+The *Min severity* dropdown hides units below the chosen level. For example, selecting *Major* removes all warning-only units, so the wall shows only the most important problems. This filter is runtime-only and resets to the configured [`defaults.minSeverity`](xref:Generic_Penalty_Box_Configuration#defaults) on the next load.
+
+![Severity dropdown](~/solutions/images/Generic_Penalty_Box_Severity_Dropdown.png)
+
+## Timeout indicator
+
+The *Show elements in timeout* checkbox in the toolbar reveals elements that are in a communications-timeout (comms-lost) state. These are hidden by default because their alarm data is stale; showing them lets you monitor how many elements are currently unreachable.
+
+## External monitoring link
+
+When [`monitoring.enabled`](xref:Generic_Penalty_Box_Configuration#monitoring) is `true`, a link icon appears on each card, and a *View in Monitoring* button appears at the bottom of the detail overlay. Both open the element in DataMiner Monitoring in a new tab, using the URL pattern from `monitoring.urlTemplate`.
+
+*monitoring.enabled: false* (default), no link on the card:
+
+![Card with monitoring link disabled](~/solutions/images/Generic_Penalty_Box_Monitoring_Link_Card_Off.png)
+
+*monitoring.enabled: true*, link icon shown on the card:
+
+![Card with monitoring link enabled](~/solutions/images/Generic_Penalty_Box_Monitoring_Link_Card_On.png)
+
+*monitoring.enabled: false*, no button in the detail overlay:
+
+![Detail overlay with monitoring link disabled](~/solutions/images/Generic_Penalty_Box_Monitoring_Link_Detail_Off.png)
+
+*monitoring.enabled: true*, *Open in Monitoring* button shown in the detail overlay:
+
+![Detail overlay with monitoring link enabled](~/solutions/images/Generic_Penalty_Box_Monitoring_Link_Detail_On.png)
+
+## Mobile and responsive layout
+
+The wall adapts to the available viewport without a separate mobile build:
+
+- Cards fill the viewport in as many columns as fit at the configured [`layout.minCardPx`](xref:Generic_Penalty_Box_Configuration#layout) width.
+- Fields listed earlier in [`cardFields`](xref:Generic_Penalty_Box_Configuration#cardfields) are hidden first as cards narrow below `layout.minLegibleCardPx`.
+- Fields marked `"pinned": true` are always visible at any card size.
+- The detail overlay slides in as a full-height panel on tablet viewports.
+
+![iPad landscape layout](~/solutions/images/Generic_Penalty_Box_Mobile_Layout.png)
+
+## Dark, light, and system theme
+
+The theme toggle in the top-right cycles through *Dark*, *Light*, and *System*. The choice is remembered per browser.
+
+![Light mode](~/solutions/images/Generic_Penalty_Box_Light_Mode.png)

solutions/toc.yml

@@ -538,6 +538,15 @@ items:
         topicUid: Open_Putty_with_DITT
       - name: Implementing DITT in a visual overview
         topicUid: Implementing_DITT_in_Visio
+    - name: Generic Penalty Box
+      topicUid: Generic_Penalty_Box_Overview
+      items:
+      - name: Installing the Generic Penalty Box
+        topicUid: Generic_Penalty_Box_Installation
+      - name: Configuring the Generic Penalty Box
+        topicUid: Generic_Penalty_Box_Configuration
+      - name: Using the Generic Penalty Box
+        topicUid: Generic_Penalty_Box_Usage
     - name: DataMiner Health Check Tool
       topicUid: DataMiner_Health_Check_Tool
       items: