Merge pull request #1660 from netalertx/next_release

Next release

Author: jokob-sk

docs/DEVICE_FILTERS.md

@@ -0,0 +1,159 @@
+## Device List & Display Configuration
+
+The **Devices** page is your primary view into what NetAlertX is monitoring. If devices are missing, unexpected devices appear, or the list doesn’t look the way you expect, the issue is often related to **filters**, **display settings**, or **device visibility configuration**.
+
+This guide focuses on adjusting your view and troubleshooting common display-related issues.
+
+---
+
+## I Don’t See a Device I Expect in *My Devices*
+
+If a device is missing from the **My Devices** list, work through these checks.
+
+### Check Active Filters
+
+The most common cause is that a filter is hiding the device.
+
+![Image](https://docs.netalertx.com/img/ADVISORIES/filters.png)
+
+![Image](https://docs.netalertx.com/img/DEVICE_MANAGEMENT/DeviceDetails_DisplaySettings.png)
+
+Review any active:
+
+* **Status filters** (Online / Offline / Down / Archived)
+* **Location** filters
+* **Owner / User** filters
+* **Device Type** filters
+* Search terms entered in the search box
+
+Clear filters first, then reload the page and check again.
+
+### Check global filters
+
+You can select devices of what statuses should be displayed in the My Devices view. This can be adjusted in the _Settings_ section - search for the `UI_MY_DEVICES` setting and verify that the statuses you want to show are selected.
+
+---
+
+### Check Whether the Device Is Hidden
+
+Some devices may be excluded from normal views depending on configuration.
+
+Examples include:
+
+* Archived devices
+* Devices marked as ignored (`NEWDEV_ignored_IPs` and `NEWDEV_ignored_MACs` settings)
+* Virtual or relationship-only devices excluded from display (setting `UI_hide_rel_types`)
+* Devices assigned to another user view or group
+
+If the device exists in the database but is intentionally hidden, it may not appear in default lists.
+
+---
+
+### Confirm the Device Has Been Detected
+
+If the device has never been scanned or synced into NetAlertX yet, it won’t appear in the UI.
+
+Things to check:
+
+* Is the device currently online?
+* Has the network scan already run?
+* Is the correct scan source enabled?
+* If using sync/import, has the sync node completed successfully?
+
+You can also trigger a manual scan and refresh the UI afterward.
+
+---
+
+### Refresh the UI Cache
+
+Sometimes device data updates correctly in the backend but the browser view hasn’t refreshed yet.
+
+Try:
+
+* Clicking the **Reload** icon in the NetAlertX header
+* Waiting for the next automatic refresh cycle
+* Performing a hard browser refresh (`Ctrl+Shift+R` / `Cmd+Shift+R`)
+
+The built-in **Reload** action is recommended over browser refresh because it clears the application’s internal cache, otherwise cache refresh might take a couple of minutes.
+
+---
+
+## Filtering Your Device View
+
+Filters help narrow large device inventories into manageable views.
+
+Common filtering options include:
+
+| Filter          | Use Case                                                    |
+| --------------- | ----------------------------------------------------------- |
+| **Status**      | Show only Online, Offline, Down, New, or Archived devices   |
+| **Location**    | View devices from a specific site or branch                 |
+| **Device Type** | Show only servers, network gear, clients, IoT devices, etc. |
+| **Owner/User**  | Limit results to a specific user or device owner            |
+| **Search**      | Find devices by hostname, IP address, MAC address, or label |
+
+Filters can be combined, which is especially useful for large installations.
+
+Example:
+
+`Status = Down` + `Location = Sydney Office`
+
+This shows only devices currently down at that site. Available filters can be configured via the `UI_columns_filters` setting.
+
+---
+
+## Related Display Settings
+
+Several UI settings affect what appears in the device list.
+
+### Hidden Connections / Virtual Devices
+
+You can hide non-essential relationships or virtual connections from the main view to reduce clutter.
+
+Useful when:
+
+* imported relationships create visual noise
+* virtual devices aren’t relevant to daily monitoring
+* you want a cleaner operational view
+
+See the `UI_hide_rel_types` setting for details.
+
+---
+
+### Dashboard Block Visibility
+
+If you’re using the dashboard alongside **Devices**, UI Settings allow you to disable blocks that aren’t useful for your workflow.
+
+Common examples:
+
+* Tiles
+* Presence widgets
+* Summary cards
+* Relationship views
+
+This can make the device list easier to focus on.
+
+To configure the above check the `UI_shown_cards`, `UI_DEV_SECTIONS` and `UI_hide_empty` settings.
+
+---
+
+### Auto Refresh
+
+If devices appear stale or statuses don’t update immediately, check **UI refresh settings** (`UI_REFRESH` setting).
+
+A refresh interval between **60–120 seconds** is usually a good balance between responsiveness and browser performance.
+
+---
+
+## Quick Troubleshooting Checklist
+
+Before digging deeper, run through this list:
+
+* [ ] Clear all active filters
+* [ ] Search by hostname, MAC address, or IP
+* [ ] Confirm the device is not archived or hidden
+* [ ] Trigger or verify a recent network scan
+* [ ] Use the NetAlertX **Reload** icon to refresh the UI cache
+* [ ] Check related UI visibility settings
+
+If the device still doesn’t appear after these checks, review the scan/import logs to confirm it has been discovered successfully by NetAlertX.

docs/PLUGINS_DEV.md

@@ -302,45 +302,8 @@ Plugin results are displayed in the web interface using various component types.
 
 ### Common Display Types
 
-**Read settings in your Python script:**
-
-```python
-from helper import get_setting_value
-
-# Read a setting by code name (prefix + function)
-api_url = get_setting_value('MYPLN_API_URL')
-api_key = get_setting_value('MYPLN_API_KEY')
-watch_columns = get_setting_value('MYPLN_WATCH')
-
-print(f"Connecting to {api_url}")
-```
-
-**Pass settings as command parameters:**
-
-Define `params` in config to pass settings as script arguments:
-
-```json
-{
-  "params": [
-    {
-      "name": "api_url",
-      "type": "setting",
-      "value": "MYPLN_API_URL"
-    }
-  ]
-}
-```
-
-Then use in `CMD`: `python3 script.py --url={api_url}`
-
 See [PLUGINS_DEV_SETTINGS.md](PLUGINS_DEV_SETTINGS.md) for complete settings documentation, and [PLUGINS_DEV_DATASOURCES.md](PLUGINS_DEV_DATASOURCES.md) for data source details.
 
-[screen1]: https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/docs/img/plugins.png                    "Screen 1"
-[screen2]: https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/docs/img/plugins_settings.png           "Screen 2"
-[screen3]: https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/docs/img/plugins_json_settings.png      "Screen 3"
-[screen4]: https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/docs/img/plugins_json_ui.png            "Screen 4"
-[screen5]: https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/docs/img/plugins_device_details.png     "Screen 5"
-
 ## Quick Reference: Key Concepts
 
 ### Plugin Output Format
@@ -394,3 +357,8 @@ See: [UI Components](PLUGINS_DEV_UI_COMPONENTS.md)
 ---
 
 
+[screen1]: https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/docs/img/plugins.png                    "Screen 1"
+[screen2]: https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/docs/img/plugins_settings.png           "Screen 2"
+[screen3]: https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/docs/img/plugins_json_settings.png      "Screen 3"
+[screen4]: https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/docs/img/plugins_json_ui.png            "Screen 4"
+[screen5]: https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/docs/img/plugins_device_details.png     "Screen 5"

docs/PLUGINS_DEV_DATA_CONTRACT.md

@@ -15,6 +15,46 @@ Plugins communicate with NetAlertX by writing results to a **pipe-delimited log
 
 **Required Columns:** 9 (mandatory) + up to 4 optional helper columns = 13 total
 
+
+## Using `plugin_helper.py`
+
+The easiest way to ensure correct output is to use the [`plugin_helper.py`](../front/plugins/plugin_helper.py) library:
+
+```python
+from plugin_helper import Plugin_Objects
+
+# Initialize with your plugin's prefix
+plugin_objects = Plugin_Objects("YOURPREFIX")
+
+# Add objects
+plugin_objects.add_object(
+    objectPrimaryId="device_id",
+    objectSecondaryId="192.168.1.1",
+    DateTime="2023-01-02 15:56:30",
+    watchedValue1="online",
+    watchedValue2=None,
+    watchedValue3=None,
+    watchedValue4=None,
+    Extra="Additional data",
+    ForeignKey="aa:bb:cc:dd:ee:ff",
+    helpVal1=None,
+    helpVal2=None,
+    helpVal3=None,
+    helpVal4=None
+)
+
+# Write results (handles formatting, sanitization, and file creation)
+plugin_objects.write_result_file()
+```
+
+The library automatically:
+
+- Validates data types
+- Sanitizes string values
+- Normalizes MAC addresses
+- Writes to the correct file location
+- Creates the file in `/tmp/log/plugins/last_result.<PREFIX>.log`
+
 ## Column Specification
 
 > [!NOTE]
@@ -134,45 +174,6 @@ device|null|2023-01-02 15:56:30|status|null|null|null|null|null|h1|h2|h3|h4
 device|null|2023-01-02 15:56:30|status|null|null|null|null|null
 ```
 
-## Using `plugin_helper.py`
-
-The easiest way to ensure correct output is to use the [`plugin_helper.py`](../front/plugins/plugin_helper.py) library:
-
-```python
-from plugin_helper import Plugin_Objects
-
-# Initialize with your plugin's prefix
-plugin_objects = Plugin_Objects("YOURPREFIX")
-
-# Add objects
-plugin_objects.add_object(
-    objectPrimaryId="device_id",
-    objectSecondaryId="192.168.1.1",
-    DateTime="2023-01-02 15:56:30",
-    watchedValue1="online",
-    watchedValue2=None,
-    watchedValue3=None,
-    watchedValue4=None,
-    Extra="Additional data",
-    ForeignKey="aa:bb:cc:dd:ee:ff",
-    helpVal1=None,
-    helpVal2=None,
-    helpVal3=None,
-    helpVal4=None
-)
-
-# Write results (handles formatting, sanitization, and file creation)
-plugin_objects.write_result_file()
-```
-
-The library automatically:
-
-- Validates data types
-- Sanitizes string values
-- Normalizes MAC addresses
-- Writes to the correct file location
-- Creates the file in `/tmp/log/plugins/last_result.<PREFIX>.log`
-
 ## De-duplication
 
 The core runs **de-duplication once per hour** on the `Plugins_Objects` table:
@@ -186,6 +187,7 @@ The core runs **de-duplication once per hour** on the `Plugins_Objects` table:
 **Required Format:** `YYYY-MM-DD HH:MM:SS`
 
 **Examples:**
+
 - `2023-01-02 15:56:30` ✅
 - `2023-1-2 15:56:30` ❌ (missing leading zeros)
 - `2023-01-02T15:56:30` ❌ (wrong separator)

docs/WORKFLOW_EXAMPLES.md

@@ -45,7 +45,7 @@ Sometimes devices are manually archived (e.g., no longer expected on the network
   ],
   "enabled": "Yes"
 }
-````
+```
 
 ### 🔍 Explanation
 

front/css/app.css

@@ -34,15 +34,15 @@ h5
 a[target="_blank"] {
     position: relative;
     display: inline-block; /* Needed for positioning */
-    padding-right: 0.6em;    /* Space for the icon */
+    padding-right: 0.55em;    /* Space for the icon */
   }
 
   a[target="_blank"]::after {
     content: '↗';
     position: absolute;
     top: 0;
-    right: 0;
-    font-size: 0.75em;
+    right: 0.3em;
+    font-size: 0.6em;
     line-height: 1;
   }
 
@@ -1546,6 +1546,11 @@ textarea[readonly],
     height: 1.5em;
 }
 
+#nextScanEta
+{
+    padding-left: 1.5em;
+}
+
 .info-icon-nav
 {
     top: -6px;

front/devices.php

@@ -97,6 +97,11 @@
             <div class="box-header">
               <div class=" col-sm-8 ">
                 <h3 id="tableDevicesTitle" class="box-title text-gray "></h3>
+                <span class="helpIconSmallTopRight">
+                  <a target="_blank" href="https://docs.netalertx.com/DEVICE_FILTERS">
+                    <i class="fa fa-circle-question"></i>
+                  </a>
+                </span>
               <!-- Next scan ETA — populated by sse_manager.js via nax:scanEtaUpdate -->
               <small id="nextScanEta" class="text-muted" style="display:none;margin-left:8px;font-weight:normal;font-size:0.75em;"></small>
               </div>
@@ -879,6 +884,7 @@ function initializeDatatable (status) {
       {className: 'iconColumn text-center',  targets: [mapIndx(COL.devIcon)]},
       {width:     '80px',        targets: [mapIndx(COL.devFirstConnection), mapIndx(COL.devLastConnection), mapIndx(COL.devParentChildrenCount), mapIndx(COL.devFQDN)] },
       {width:     '85px',        targets: [mapIndx(COL.devIsRandomMac)] },
+      {width:     '130px',       targets: [mapIndx(COL.devLastIP), mapIndx(COL.devIpLong)] },
       {width:     '30px',        targets: [mapIndx(COL.devIcon), mapIndx(COL.devStatus), mapIndx(COL.rowid), mapIndx(COL.devParentPort)] },
       {orderData: [mapIndx(COL.devIpLong)],  targets: mapIndx(COL.devLastIP) },
 
@@ -961,16 +967,14 @@ function initializeDatatable (status) {
       {targets: [mapIndx(COL.devLastIP)],
         'createdCell': function (td, cellData, rowData, row, col) {
             if (!emptyArr.includes(cellData)){
-              $(td).html (`<span class="anonymizeIp">
-                            <a href="http://${cellData}" class="pointer" target="_blank">
-                                ${cellData}
-                            </a>
-                            <span class="alignRight lockIcon">
+              $(td).html (`<div class="anonymizeIp alignRight">
+                              <a href="http://${cellData}" class="pointer" target="_blank">
+                                  ${cellData}
+                              </a>
                               <a href="https://${cellData}" class="pointer" target="_blank">
                                 <i class="fa fa-lock "></i>
                               </a>
-                            <span>
-                          <span>`);
+                          </div>`);
             } else {
               $(td).html ('');
             }