Merge branch 'main' of https://github.com/jokob-sk/NetAlertX

Currently translated at 100.0% (743 of 743 strings)

Translation: NetAlertX/core
Translate-URL: https://hosted.weblate.org/projects/pialert/core/it/

.github/ISSUE_TEMPLATE/i-have-an-issue.yml

@@ -59,12 +59,15 @@ body:
   validations:
     required: false
 - type: dropdown
+  id: installation_type
   attributes:
     label: What installation are you running?
     options:
       - Production (netalertx)
       - Dev (netalertx-dev)
       - Home Assistant (addon)
+      - Home Assistant fa (full-access addon)
+      - Bare-metal (community only support - Check Discord)
   validations:
     required: true
 - type: textarea

.github/ISSUE_TEMPLATE/setup-help.yml

@@ -44,12 +44,15 @@ body:
   validations:
     required: false
 - type: dropdown
+  id: installation_type
   attributes:
     label: What installation are you running?
     options:
       - Production (netalertx)
       - Dev (netalertx-dev)
       - Home Assistant (addon)
+      - Home Assistant fa (full-access addon)
+      - Bare-metal (community only support - Check Discord)
   validations:
     required: true
 - type: textarea

.github/tweet.md

@@ -0,0 +1,2 @@
+🎉 New release: **v25.4.1 - 🔀 Workflows - automate device management ** is live! 🚀
+Check it out here: https://github.com/jokob-sk/NetAlertX/releases/tag/v25.4.1

.github/workflows/code_checks.yml

@@ -1,4 +1,4 @@
-name: URL Path Check
+name: Code checks
 on:
   push:
     branches:
@@ -25,4 +25,9 @@ jobs:
           else
             echo "✅ No absolute path URLs found."
           fi
+      - name: Check Python syntax
+        run: |
+          set -e
+          echo "🔍 Checking Python syntax..."
+          find . -name "*.py" -print0 | xargs -0 -n1 python3 -m py_compile
 

.github/workflows/label-issues.yml

@@ -0,0 +1,43 @@
+name: Label Issues by Installation Type
+
+on:
+  issues:
+    types: [opened]
+
+permissions:
+  issues: write
+
+jobs:
+  add-label:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Get issue content
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const body = context.payload.issue.body;
+
+            const lowerBody = body.toLowerCase();
+
+            let labelsToAdd = [];
+
+            if (lowerBody.includes('bare-metal')) {
+              labelsToAdd.push('bare-metal ❗');
+            }
+
+            if (lowerBody.includes('home assistant')) {
+              labelsToAdd.push('Home Assistant 🏠');
+            }
+
+            if (lowerBody.includes('production (netalertx)') || lowerBody.includes('dev (netalertx-dev)')) {
+              labelsToAdd.push('Docker 🐋');
+            }
+
+            if (labelsToAdd.length > 0) {
+              await github.rest.issues.addLabels({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                labels: labelsToAdd
+              });
+            }

README.md

@@ -41,6 +41,10 @@ Send notifications to more than 80+ services, including Telegram via [Apprise](h
 Feed your data and device changes into [Home Assistant](https://github.com/jokob-sk/NetAlertX/blob/main/docs/HOME_ASSISTANT.md), read [API endpoints](https://github.com/jokob-sk/NetAlertX/blob/main/docs/API.md), or use [Webhooks](https://github.com/jokob-sk/NetAlertX/blob/main/docs/WEBHOOK_N8N.md) to setup custom automation flows. You can also 
 build your own scanners with the [Plugin system](https://github.com/jokob-sk/NetAlertX/tree/main/docs/PLUGINS.md#readme) in as little as [15 minutes](https://www.youtube.com/watch?v=cdbxlwiWhv8).
 
+### Workflows
+
+The [workflows module](https://github.com/jokob-sk/NetAlertX/blob/main/docs/WORKFLOWS.md) in NetAlertX allows to automate repetitive tasks, making network management more efficient. Whether you need to assign newly discovered devices to a specific Network Node, auto-group devices from a given vendor, unarchive a device if detected online, or automatically delete devices, this module provides the flexibility to tailor the automations to your needs.
+
 
 ## 📚 Documentation
 <!--- --------------------------------------------------------------------- --->

docs/DEBUG_PLUGINS.md

@@ -2,7 +2,7 @@
 
 ## High-level overview
 
-If a Plugin supplies data to the main app it's doine either vie a SQL query or via a script that updates the `last_result.log` file in the plugin folder (`front/plugins/<plugin>`).
+If a Plugin supplies data to the main app it's done either vie a SQL query or via a script that updates the `last_result.log` file in the plugin log folder (`app/log/plugins/`).
 
 For a more in-depth overview on how plugins work check the [Plugins development docs](https://github.com/jokob-sk/NetAlertX/blob/main/docs/PLUGINS.md).
 

docs/DOCKER_COMPOSE.md

@@ -1,7 +1,7 @@
 # `docker-compose.yaml` Examples
 
 > [!NOTE] 
-> The container needs to run in `network_mode:"host"`. 
+> The container needs to run in `network_mode:"host"`. This also means that not all functionality is supported on a Windows host as Docker for Windows doesn't support this networking option. 
 
 ### Example 1
 
@@ -122,7 +122,6 @@ services:
     environment:
       - TZ=Europe/London
       - PORT=20211
-    # network_mode: host
     networks:
       - outside
     deploy:
@@ -130,10 +129,6 @@ services:
       replicas: 1
       restart_policy:
         condition: on-failure
-      # placement: # ✅ Placement is now correctly inside deploy
-      # constraints:
-      #   - node.role == manager
-      #   - node.labels.device == NUC2
 
 networks:
   outside:

docs/HOME_ASSISTANT.md

@@ -3,7 +3,7 @@
 NetAlertX comes with MQTT support, allowing you to show all detected devices as devices in Home Assistant. It also supplies a collection of stats, such as number of online devices.
 
 > [!TIP]
-> You can install NetAlertX also as a Home Assistant addon [![Home Assistant](https://img.shields.io/badge/Repo-blue?logo=home-assistant&style=for-the-badge&color=0aa8d2&logoColor=fff&label=Add)](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Falexbelgium%2Fhassio-addons) via the [alexbelgium/hassio-addons](https://github.com/alexbelgium/hassio-addons/). This is only possible if you run a supervised instance of Home Assistant. If not, you can still run NetAlertX in a separate Docker container and follow this guide to configure MQTT.
+> You can install NetAlertX also as a Home Assistant addon [![Home Assistant](https://img.shields.io/badge/Repo-blue?logo=home-assistant&style=for-the-badge&color=0aa8d2&logoColor=fff&label=Add)](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Falexbelgium%2Fhassio-addons) via the [alexbelgium/hassio-addons](https://github.com/alexbelgium/hassio-addons/) repository. This is only possible if you run a supervised instance of Home Assistant. If not, you can still run NetAlertX in a separate Docker container and follow this guide to configure MQTT.
 
 ## ⚠ Note 
 

docs/INSTALLATION.md

@@ -2,7 +2,7 @@
 
 ## Installation options
 
-NetAlertX can be installed several ways. The best supported option is Docker, followed by a supervised the Home Assistant instance, as an Unraid app and lastly on bare metal. 
+NetAlertX can be installed several ways. The best supported option is Docker, followed by a supervised Home Assistant instance, as an Unraid app, and lastly, on bare metal. 
 
 - [[Installation] Docker (recommended)](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md) 
 - [[Installation] Home Assistant](https://github.com/alexbelgium/hassio-addons/tree/master/netalertx) 

docs/LOGGING.md

@@ -0,0 +1,26 @@
+# Logging
+
+NetAlertX comes with several logs that help to identify application issues. 
+
+For plugin-specific log debugging, please read the [Debug Plugins](./DEBUG_PLUGINS.md) guide.
+
+When debugging any issue, increase the `LOG_LEVEL` Setting as per the [Debug tips](./DEBUG_TIPS.md) documentation.
+
+
+## Main logs
+
+You can find most of the logs exposed in the UI under _Maintenance -> Logs_. 
+
+If the UI is inaccessible, you can access them under `/app/log`.
+
+![Logs](./img/LOGGING/maintenance_logs.png)
+
+In the _Maintennace -> Logs_ you can **Purge logs**, download the full log file or Filter the lines with some substring to narrow down your search. 
+
+## Plugin logging
+
+If a Plugin supplies data to the main app it's done either vie a SQL query or via a script that updates the `last_result.log` file in the plugin log folder (`app/log/plugins/`). These files are processed at the end of the scan and deleted on successful processing.
+
+The data is in most of the cases then displayed in the application under _Integrations -> Plugins_ (or _Device -> Plugins_ if the plugin is supplying device-specific data). 
+
+![Plugin objects](./img/LOGGING/logging_integrations_plugins.png)

docs/NAME_RESOLUTION.md

@@ -0,0 +1,47 @@
+# Device Name Resolution
+
+Name resolution in NetAlertX relies on multiple plugins to resolve device names from IP addresses. If you are seeing `(name not found)` as device names, follow these steps to diagnose and fix the issue.
+
+## Required Plugins
+
+For best results, ensure the following name resolution plugins are enabled:
+
+- **AVAHISCAN** – Uses mDNS/Avahi to resolve local network names.
+- **NBTSCAN** – Queries NetBIOS to find device names.
+- **NSLOOKUP** – Performs standard DNS lookups.
+
+You can check which plugins are active in your _Settings_ section and enable any that are missing.
+
+There are other plugins that can supply device names as well, but they rely on bespoke hardware and services. See [Plugins overview](./PLUGINS.md) for details and look for plugins with name discovery (🆎) features.
+
+## Checking Logs
+
+If names are not resolving, check the logs for errors or timeouts.
+
+See how to explore logs in the [Logging guide](./LOGGING.md).
+
+Logs will show which plugins attempted resolution and any failures encountered.
+
+## Adjusting Timeout Settings
+
+If resolution is slow or failing due to timeouts, increase the timeout settings in your configuration, for example.
+
+```ini
+NSLOOKUP_RUN_TIMEOUT = 30
+```
+
+Raising the timeout may help if your network has high latency or slow DNS responses.
+
+## Checking Plugin Objects
+
+Each plugin stores results in its respective object. You can inspect these objects to see if they contain valid name resolution data.
+
+See [Logging guide](./LOGGING.md) and [Debug plugins](./DEBUG_PLUGINS.md) guides for details.
+
+If the object contains no results, the issue may be with DNS settings or network access.
+
+## Improving name resolution
+
+For more details how to improve name resolution refer to the 
+[Reverse DNS Documentation](./REVERSE_DNS.md).
+

docs/PLUGINS.md

@@ -8,17 +8,38 @@ NetAlertX supports additional plugins to extend its functionality, each with its
 ## ⚡ Quick start
 
 > [!TIP]
-> You can load additional Plugins via the General -> `LOADED_PLUGINS` setting. 
+> You can load additional Plugins via the General -> `LOADED_PLUGINS` setting. You need to save the settings for the new plugins to load (cache/page reload may be necessary). 
+> ![Loaded plugins settings](./img/PLUGINS/loaded_plugins_setting.png)
 
-1. Pick your `🔍 dev scanner` plugin (e.g. `ARPSCAN` or `NMAPDEV`), or import devices into the application with an `📥 importer` plugin. (See **✅Enabling plugins** below)
+1. Pick your `🔍 dev scanner` plugin (e.g. `ARPSCAN` or `NMAPDEV`), or import devices into the application with an `📥 importer` plugin. (See **Enabling plugins** below)
 2. Pick a `▶️ publisher` plugin, if you want to send notifications. If you don't see a publisher you'd like to use, look at the  [📚_publisher_apprise](/front/plugins/_publisher_apprise/) plugin which is a proxy for over 80 notification services. 
 3. Setup your [Network topology diagram](./NETWORK_TREE.md)
 4. Fine-tune [Notifications](./NOTIFICATIONS.md)
-5. [Backup your setup](./BACKUPS.md)
-6. Contribute and [Create custom plugins](./PLUGINS_DEV.md)
+5. Setup [Workflows](./WORKFLOWS.md)
+6. [Backup your setup](./BACKUPS.md)
+7. Contribute and [Create custom plugins](./PLUGINS_DEV.md)
 
 
-## 📑 Available Plugins
+## Plugin types
+
+| Plugin type    | Icon | Description                                                      | When to run                         | Required | Data source [?](./PLUGINS_DEV.md) |
+| -------------- | ---- | ---------------------------------------------------------------- | ----------------------------------- | -------- | ------------------------------------- |
+| publisher      | ▶️    | Sending notifications to services.                               | `on_notification`                   | ✖        | Script                                |
+| dev scanner    | 🔍    | Create devices in the app, manages online/offline device status. | `schedule`                          | ✖        | Script / SQLite DB                    |
+| name discovery | 🆎    | Discovers names of devices via various protocols.                | `before_name_updates`, `schedule`   | ✖        | Script                                |
+| importer       | 📥    | Importing devices from another service.                          | `schedule`                          | ✖        | Script / SQLite DB                    |
+| system         | ⚙    | Providing core system functionality.                             | `schedule` / always on              | ✖/✔      | Script / Template                     |
+| other          | ♻    | Other plugins                                                    | misc                                | ✖        | Script / Template                     |
+
+## Features
+
+| Icon | Description                                                  |
+| ---- | ------------------------------------------------------------ |
+| 🖧    | Auto-imports the network topology diagram                    |
+| 🔄    | Has the option to sync some data back into the plugin source |
+
+
+## Available Plugins
  
 Device-detecting plugins insert values into the `CurrentScan` database table.  The plugins that are not required are safe to ignore, however, it makes sense to have at least some device-detecting plugins enabled, such as `ARPSCAN` or `NMAPDEV`. 
 
@@ -36,7 +57,7 @@ Device-detecting plugins insert values into the `CurrentScan` database table.  T
 | `DHCPLSS`     | 🔍/📥/🆎| Import devices from DHCP leases          |           |          | Script       | [dhcp_leases](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/dhcp_leases/)                        |
 | `DHCPSRVS`    | ♻       | DHCP servers                              |           |          | Script       | [dhcp_servers](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/dhcp_servers/)                      |
 | `FREEBOX`     | 🔍/♻/🆎| Pull data and names from Freebox/Iliadbox |          |          | Script       | [freebox](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/freebox/)                                 |
-| `ICMP`        | 🔍      | ICMP (ping) status checker                |           |          | Script       | [icmp_scan](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/icmp_scan/)                            |
+| `ICMP`        | ♻      | ICMP (ping) status checker                |           |          | Script       | [icmp_scan](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/icmp_scan/)                            |
 | `INTRNT`      | 🔍      | Internet IP scanner                       |           |          | Script       | [internet_ip](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/internet_ip/)                        |
 | `INTRSPD`     | ♻       | Internet speed test                       |           |          | Script       | [internet_speedtest](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/internet_speedtest/)          |
 | `IPNEIGH`     | 🔍       | Scan ARP (IPv4) and NDP (IPv6) tables    |           |          | Script       | [ipneigh](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/ipneigh/)                                |
@@ -72,27 +93,9 @@ Device-detecting plugins insert values into the `CurrentScan` database table.  T
 > ❌ marked for removal
 > ⌚It's recommended to use the same schedule interval for all plugins responsible for discovering new devices.
 
-## Plugin types
 
 
-| Plugin type    | Icon | Description                                                      | When to run                         | Required | Data source [?](./PLUGINS_DEV.md) |
-| -------------- | ---- | ---------------------------------------------------------------- | ----------------------------------- | -------- | ------------------------------------- |
-| publisher      | ▶️    | Sending notifications to services.                               | `on_notification`                   | ✖        | Script                                |
-| dev scanner    | 🔍    | Create devices in the app, manages online/offline device status. | `schedule`                          | ✖        | Script / SQLite DB                    |
-| name discovery | 🆎    | Discovers names of devices via various protocols.                | `before_name_updates`, `schedule`   | ✖        | Script                                |
-| importer       | 📥    | Importing devices from another service.                          | `schedule`                          | ✖        | Script / SQLite DB                    |
-| system         | ⚙    | Providing core system functionality.                             | `schedule` / always on              | ✖/✔      | Script / Template                     |
-| other          | ♻    | Other plugins                                                    | misc                                | ✖        | Script / Template                     |
-
-## Features
-
-| Icon | Description                                                  |
-| ---- | ------------------------------------------------------------ |
-| 🖧    | Auto-imports the network topology diagram                    |
-| 🔄    | Has the option to sync some data back into the plugin source |
-
-
-## ✅Enabling plugins
+## Enabling plugins
 
 Plugins can be enabled via Settings, and can be disabled as needed. 
 

docs/REMOTE_NETWORKS.md

@@ -31,7 +31,7 @@ The following workarounds should work for most complex network setups.
 
 ## Supplementing Plugins
 
-You can use supplementary plugins that employ alternate methods. Protocols used by the `SNMPDSC` or `DHCPLSS` plugins are widely supported on different routers and can be effective as workarounds. Check the [plugins list](https://github.com/jokob-sk/NetAlertX/blob/main/docs/PLUGINS.md) to find a plugin that works with your router and network setup.
+You can use supplementary plugins that employ alternate methods. Protocols used by the `SNMPDSC` or `DHCPLSS` plugins are widely supported on different routers and can be effective as workarounds. Check the [plugins list](./PLUGINS.md) to find a plugin that works with your router and network setup.
 
 ## Multiple NetAlertX Instances
 

docs/SYNOLOGY_GUIDE.md

@@ -51,7 +51,7 @@ services:
 
 ![Project settings](./img/SYNOLOGY/07_Create_project.png)
 
-7. Replace the paths to your volume and/or comment out unnecessary line(s):
+7. Replace the paths to your volume and comment out unnecessary line(s):
 
 - This is only an example, your paths will differ.
 

docs/WEB_UI_PORT_DEBUG.md

@@ -1,49 +1,70 @@
 # Debugging inaccessible UI
 
-## 1. Port conflicts
+The application uses the following default ports:
 
-When opening an issue please:
+- **Web UI**: `20211`  
+- **GraphQL API**: `20212`
+
+The **Web UI** is served by an **nginx** server, while the **API backend** runs on a **Flask (Python)** server.
+
+## Changing Ports
+
+- To change the **Web UI** port, update the `PORT` environment variable in the `docker-compose.yml` file.
+- To change the **GraphQL API** port, use the `GRAPHQL_PORT` setting, either directly or via Docker:
+  ```yaml
+  APP_CONF_OVERRIDE={"GRAPHQL_PORT":"20212"}
+  ```
+
+For more information, check the [Docker installation guide](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md).
+
+## Possible issues and troubleshooting
+
+Follow all of the below in order to disqualify potential causes of issues and to troubleshoot these problems faster.
+
+### 1. Port conflicts
+
+When opening an issue or debugging:
 
 1. Include a screenshot of what you see when accessing `HTTP://<your rpi IP>/20211` (or your custom port)
 1. [Follow steps 1, 2, 3, 4  on this page](./DEBUG_TIPS.md) 
 1. Execute the following in the container to see the processes and their ports and submit a screenshot of the result:
-   1. `sudo apk add lsof`
-   1. `sudo lsof -i`
-1. Try running the `nginx` command in the container
-   1. if you get `nginx: [emerg] bind() to 0.0.0.0:20211 failed (98: Address in use)` try using a different port number
+   - `sudo apk add lsof`
+   - `sudo lsof -i`
+1. Try running the `nginx` command in the container:
+   - if you get `nginx: [emerg] bind() to 0.0.0.0:20211 failed (98: Address in use)` try using a different port number
 
 
 ![lsof ports](./img/WEB_UI_PORT_DEBUG/container_port.png)
 
-## 2. JavaScript issues 
+### 2. JavaScript issues 
 
 Check for browser console (F12 browser dev console) errors + check different browsers.
 
-## 3. Clear the app cache and cached JavaScript files
+### 3. Clear the app cache and cached JavaScript files
 
 Refresh the browser cache (usually shoft + refresh), try a private window, or different browsers. Please also refresh the app cache by clicking the 🔃 (reload) button in the header of the application. 
 
-## 4. Disable proxy
+### 4. Disable proxies
 
 If you have any reverse proxy or similar, try disabling it. 
 
-## 5. Disable your firewall
+### 5. Disable your firewall
 
 If you are using a firewall, try to temporarily disabling it. 
 
-## 6. Post your docker start details
+### 6. Post your docker start details
 
 If you haven't, post your docker compose/run command.
 
-## 7. Check for errors in your PHP/NGINX error logs
+### 7. Check for errors in your PHP/NGINX error logs
 
-In the container execute:
+In the container execute and investigate:
 
 `cat /var/log/nginx/error.log`
 
 `cat /app/log/app.php_errors.log`
 
-## 8. Make sure permissions are correct
+### 8. Make sure permissions are correct
 
 > [!TIP]
 > You can try to start the container without mapping the `/app/config` and `/app/db` dirs and if the UI shows up then the issue is most likely related to your file system permissions or file ownership. 

docs/WORKFLOWS.md

@@ -15,8 +15,13 @@ Below are a few examples that demonstrate how this module can be used to simplif
 
 ### Triggers
 
+![Trigger example](./img/WORKFLOWS/trigger.jpg)
+
 Triggers define the event that activates a workflow. They monitor changes to objects within the system, such as updates to devices or the insertion of new entries. When the specified event occurs, the workflow is executed.
 
+> [!TIP]
+> Workflows not running? Check the [Workflows debugging](./WORKFLOWS_DEBUGGING.md) guide how to troubleshoot triggers and conditions.
+
 #### Example Trigger:
 - **Object Type**: `Devices`
 - **Event Type**: `update`
@@ -32,7 +37,7 @@ Conditions determine whether a workflow should proceed based on certain criteria
 > [!TIP]
 > To better understand how to use specific Device fields, please read through the [Database overview](./DATABASE.md) guide.
 
-### Example Condition:
+#### Example Condition:
 - **Logic**: `AND`
   - **Field**: `devVendor`
   - **Operator**: `contains` (case in-sensitive)
@@ -48,7 +53,7 @@ Actions define the tasks that the workflow will perform once the conditions are
 
 You can include multiple actions that should execute once the conditions are met.
 
-### Example Action:
+#### Example Action:
 - **Action Type**: `update_field`
   - **Field**: `devIsNew`
   - **Value**: `0`

docs/WORKFLOWS_DEBUGGING.md

@@ -0,0 +1,38 @@
+# Workflows debugging and troubleshooting
+
+> [!TIP]
+> Before troubleshooting, please ensure you have [Debugging enabled](./DEBUG_TIPS.md).
+
+Workflows are triggered by various events. These events are captured and listed in the _Integrations -> App Events_ section of the application. 
+
+## Troubleshooting triggers
+
+> [!NOTE]
+> Workflow events are processed once every 5 seconds. However, if a scan or other background tasks are running, this can cause a delay up to a few minutes. 
+
+If an event doesn't trigger a workflow as expected, check the _App Events_ section for the event. You can filter these by the ID of the device (`devMAC` or `devGUID`). 
+
+![App events search](./img/WORKFLOWS/workflows_app_events_search.png)
+
+Once you find the _Event Guid_ and _Object GUID_, use them to find relevant debug entries. 
+
+Navigate to _Mainetenace -> Logs_ where you can filter the logs based on the _Event or Object GUID_. 
+
+![Log events search](./img/WORKFLOWS/workflows_logs_search.png)
+
+Below you can find some example `app.log` entries that will help you understand why a Workflow was or was not triggered.
+
+```bash
+16:27:03 [WF] Checking if '13f0ce26-1835-4c48-ae03-cdaf38f328fe' triggers the workflow 'Sample Device Update Workflow'
+16:27:03 [WF] self.triggered 'False' for event '[[155], ['13f0ce26-1835-4c48-ae03-cdaf38f328fe'], [0], ['2025-04-02 05:26:56'], ['Devices'], ['050b6980-7af6-4409-950d-08e9786b7b33'], ['DEVICES'], ['00:11:32:ef:a5:6c'], ['192.168.1.82'], ['050b6980-7af6-4409-950d-08e9786b7b33'], [None], [0], [0], ['devPresentLastScan'], ['online'], ['update'], [None], [None], [None], [None]] and trigger {"object_type": "Devices", "event_type": "insert"}' 
+16:27:03 [WF] Checking if '13f0ce26-1835-4c48-ae03-cdaf38f328fe' triggers the workflow 'Location Change'
+16:27:03 [WF] self.triggered 'True' for event '[[155], ['13f0ce26-1835-4c48-ae03-cdaf38f328fe'], [0], ['2025-04-02 05:26:56'], ['Devices'], ['050b6980-7af6-4409-950d-08e9786b7b33'], ['DEVICES'], ['00:11:32:ef:a5:6c'], ['192.168.1.82'], ['050b6980-7af6-4409-950d-08e9786b7b33'], [None], [0], [0], ['devPresentLastScan'], ['online'], ['update'], [None], [None], [None], [None]] and trigger {"object_type": "Devices", "event_type": "update"}' 
+16:27:03 [WF] Event with GUID '13f0ce26-1835-4c48-ae03-cdaf38f328fe' triggered the workflow 'Location Change'
+```
+
+Note how one trigger executed, but the other didn't based on different `"event_type"` values. One is `"event_type": "insert"`, the other `"event_type": "update"`.
+
+Given the Event is a update event (note `...['online'], ['update'], [None]...` in the event structure), the `"event_type": "insert"` trigger didn't execute.
+
+
+

front/css/app.css

@@ -1857,6 +1857,11 @@ input[readonly] {
     padding: 5px;
 }
 
+.workflows 
+{
+    max-width: 800px;
+}
+
 .workflows .col-sm-12, .workflows .col-sx-12
 {
     padding-right: 5px;

front/deviceDetailsEdit.php

@@ -266,7 +266,7 @@
       
       })
     
-      }, 1);
+      }, 100);
     });
   
   }
@@ -338,6 +338,7 @@
 
 
   // -----------------------------------------------------------------------------
+  // Save device data to DB
   function setDeviceData(direction = '', refreshCallback = '') {
     // Check MAC
     if (mac === '') {

front/index.php

@@ -2,10 +2,13 @@
 <link rel="stylesheet" href="css/app.css">
 
 <?php
-require dirname(__FILE__).'/php/server/init.php';
+
 //------------------------------------------------------------------------------
 // check if authenticated
-require_once  $_SERVER['DOCUMENT_ROOT'] . '/php/templates/security.php';
+// Be CAREFUL WHEN INCLUDING NEW PHP FILES
+require_once $_SERVER['DOCUMENT_ROOT'] . '/php/server/db.php';
+require_once $_SERVER['DOCUMENT_ROOT'] . '/php/templates/language/lang.php';
+require_once $_SERVER['DOCUMENT_ROOT'] . '/php/templates/security.php';
 
 $CookieSaveLoginName = 'NetAlertX_SaveLogin';
 

front/php/templates/language/fr_fr.json

@@ -683,15 +683,15 @@
     "WF_Condition_value": "Valeur",
     "WF_Conditions": "Conditions",
     "WF_Conditions_logic_rules": "Règles logiques",
-    "WF_Duplicate": "",
+    "WF_Duplicate": "Dupliquer le workflow",
     "WF_Enabled": "Workflow activé",
-    "WF_Export": "",
-    "WF_Export_Copy": "",
-    "WF_Import": "",
-    "WF_Import_Copy": "",
+    "WF_Export": "Exporter le workflow",
+    "WF_Export_Copy": "Copier le workflow ci-dessous pour pouvoir l'importer au besoin.",
+    "WF_Import": "Importer un workflow",
+    "WF_Import_Copy": "Coller le workflow précédemment copié.",
     "WF_Name": "Nom du workflow",
     "WF_Remove": "Supprimer le workflow",
-    "WF_Remove_Copy": "",
+    "WF_Remove_Copy": "Voulez-vous supprimer ce workflow ?",
     "WF_Save": "Enregistrer les workflows",
     "WF_Trigger": "Déclencheur",
     "WF_Trigger_event_type": "Type d'événement",
@@ -742,4 +742,4 @@
     "settings_update_item_warning": "Mettre à jour la valeur ci-dessous. Veillez à bien suivre le même format qu'auparavant. <b>Il n'y a pas de pas de contrôle.</b>",
     "test_event_icon": "fa-vial-circle-check",
     "test_event_tooltip": "Enregistrer d'abord vos modifications avant de tester vôtre paramétrage."
-}
+}

front/php/templates/language/it_it.json

@@ -683,15 +683,15 @@
     "WF_Condition_value": "Valore",
     "WF_Conditions": "Condizioni",
     "WF_Conditions_logic_rules": "Regole logiche",
-    "WF_Duplicate": "",
+    "WF_Duplicate": "Flusso di lavoro duplicato",
     "WF_Enabled": "Flusso di lavoro abilitato",
-    "WF_Export": "",
-    "WF_Export_Copy": "",
-    "WF_Import": "",
-    "WF_Import_Copy": "",
+    "WF_Export": "Esporta flusso di lavoro",
+    "WF_Export_Copy": "Copia il flusso di lavoro sottostante e importalo dove necessario.",
+    "WF_Import": "Importa flusso di lavoro",
+    "WF_Import_Copy": "Incolla il flusso di lavoro copiato in precedenza.",
     "WF_Name": "Nome flusso di lavoro",
     "WF_Remove": "Rimuovi flusso di lavoro",
-    "WF_Remove_Copy": "",
+    "WF_Remove_Copy": "Vuoi rimuovere questo flusso di lavoro?",
     "WF_Save": "Salva flussi di lavoro",
     "WF_Trigger": "Trigger",
     "WF_Trigger_event_type": "Tipo evento",
@@ -742,4 +742,4 @@
     "settings_update_item_warning": "Aggiorna il valore qui sotto. Fai attenzione a seguire il formato precedente. <b>La convalida non viene eseguita.</b>",
     "test_event_icon": "fa-vial-circle-check",
     "test_event_tooltip": "Salva le modifiche prima di provare le nuove impostazioni."
-}
+}

front/php/templates/language/ru_ru.json

@@ -8,7 +8,7 @@
     "About_Design": "Разработан:",
     "About_Exit": "Зарегистрироваться",
     "About_Title": "Сетевой сканер и система уведомлений",
-    "AppEvents_AppEventProcessed": "",
+    "AppEvents_AppEventProcessed": "Обработанный",
     "AppEvents_DateTimeCreated": "Журнал",
     "AppEvents_Extra": "Дополнительно",
     "AppEvents_GUID": "GUID события приложения",
@@ -22,7 +22,7 @@
     "AppEvents_ObjectPlugin": "Связанный плагин",
     "AppEvents_ObjectPrimaryID": "Первичный ID",
     "AppEvents_ObjectSecondaryID": "Вторичный ID",
-    "AppEvents_ObjectStatus": "Состояние (во время входа в систему)",
+    "AppEvents_ObjectStatus": "Зарегистрированный статус",
     "AppEvents_ObjectStatusColumn": "Колонка состояния",
     "AppEvents_ObjectType": "Тип объекта",
     "AppEvents_Plugin": "Плагин",
@@ -70,7 +70,7 @@
     "DevDetail_Copy_Device_Tooltip": "Скопируйте данные с устройства из раскрывающегося списка. Все на этой странице будет перезаписано",
     "DevDetail_CustomProperties_Title": "Пользовательские свойства",
     "DevDetail_CustomProps_reset_info": "Это удалит ваши пользовательские свойства на этом устройстве и вернет их к значению по умолчанию.",
-    "DevDetail_DisplayFields_Title": "Дисплей",
+    "DevDetail_DisplayFields_Title": "Отображение",
     "DevDetail_EveandAl_AlertAllEvents": "Оповещения о событиях",
     "DevDetail_EveandAl_AlertDown": "Оповещение о доступности",
     "DevDetail_EveandAl_Archived": "Архив",
@@ -225,7 +225,7 @@
     "Device_TableHead_Name": "Имя",
     "Device_TableHead_NetworkSite": "Сайт устройства",
     "Device_TableHead_Owner": "Владелец",
-    "Device_TableHead_Parent_MAC": "MAC род. узла",
+    "Device_TableHead_Parent_MAC": "Родительский узел сети",
     "Device_TableHead_Port": "Порт",
     "Device_TableHead_PresentLastScan": "Присутствие",
     "Device_TableHead_RowID": "ID строки",
@@ -363,8 +363,8 @@
     "Maintenance_Title": "Инструменты обслуживания",
     "Maintenance_Tool_DownloadConfig": "Экспорт настроек",
     "Maintenance_Tool_DownloadConfig_text": "Загрузите полную резервную копию конфигурации настроек, хранящуюся в файле <code>app.conf</code>.",
-    "Maintenance_Tool_DownloadWorkflows": "",
-    "Maintenance_Tool_DownloadWorkflows_text": "",
+    "Maintenance_Tool_DownloadWorkflows": "Экспорт Workflow",
+    "Maintenance_Tool_DownloadWorkflows_text": "Загрузите полную резервную копию ваших Workflow, хранящихся в файле <code> hairpflows.json </code>.",
     "Maintenance_Tool_ExportCSV": "Экспорт устройств (csv)",
     "Maintenance_Tool_ExportCSV_noti": "Экспорт устройств (csv)",
     "Maintenance_Tool_ExportCSV_noti_text": "Вы уверены, что хотите создать файл CSV?",
@@ -463,7 +463,7 @@
     "NETWORK_DEVICE_TYPES_description": "Какие типы устройств разрешено использовать в качестве сетевых устройств в представлении Сеть. Тип устройства должен точно соответствовать настройке <code>Type</code> для конкретного устройства в сведениях об устройстве. Добавьте его на устройство с помощью кнопки <code>+</code>. Не удаляйте существующие типы, а только добавляйте новые.",
     "NETWORK_DEVICE_TYPES_name": "Типы сетевых устройств",
     "Navigation_About": "О NetAlertX",
-    "Navigation_AppEvents": "",
+    "Navigation_AppEvents": "События приложения",
     "Navigation_Devices": "Устройства",
     "Navigation_Donations": "Пожертвования",
     "Navigation_Events": "События",
@@ -670,32 +670,32 @@
     "UI_REFRESH_name": "Автоматическое обновление интерфейса",
     "VERSION_description": "Вспомогательное значение версии или метки времени, позволяющее проверить, было ли приложение обновлено.",
     "VERSION_name": "Версия или временная метка",
-    "WF_Action_Add": "",
-    "WF_Action_field": "",
-    "WF_Action_type": "",
-    "WF_Action_value": "",
-    "WF_Actions": "",
-    "WF_Add": "",
-    "WF_Add_Condition": "",
-    "WF_Add_Group": "",
-    "WF_Condition_field": "",
-    "WF_Condition_operator": "",
-    "WF_Condition_value": "",
-    "WF_Conditions": "",
-    "WF_Conditions_logic_rules": "",
-    "WF_Duplicate": "",
-    "WF_Enabled": "",
-    "WF_Export": "",
-    "WF_Export_Copy": "",
-    "WF_Import": "",
-    "WF_Import_Copy": "",
-    "WF_Name": "",
-    "WF_Remove": "",
-    "WF_Remove_Copy": "",
-    "WF_Save": "",
-    "WF_Trigger": "",
-    "WF_Trigger_event_type": "",
-    "WF_Trigger_type": "",
+    "WF_Action_Add": "Добавить действие",
+    "WF_Action_field": "Поле",
+    "WF_Action_type": "Тип",
+    "WF_Action_value": "Значение",
+    "WF_Actions": "Действия",
+    "WF_Add": "Добавить Workflow",
+    "WF_Add_Condition": "Добавить условие",
+    "WF_Add_Group": "Добавить группу",
+    "WF_Condition_field": "Поле",
+    "WF_Condition_operator": "Оператор",
+    "WF_Condition_value": "Значение",
+    "WF_Conditions": "Условия",
+    "WF_Conditions_logic_rules": "Правила логики",
+    "WF_Duplicate": "Дублировать Workflow",
+    "WF_Enabled": "Включить Workflow",
+    "WF_Export": "Экспорт Workflow",
+    "WF_Export_Copy": "Скопируйте приведенный ниже Workflow и импортируйте его, где это необходимо.",
+    "WF_Import": "Импорт Workflow",
+    "WF_Import_Copy": "Вставьте в Workflow, который вы скопировали ранее.",
+    "WF_Name": "Имя Workflow",
+    "WF_Remove": "Удалить Workflow",
+    "WF_Remove_Copy": "Вы хотите удалить этот Workflow?",
+    "WF_Save": "Сохранить Workflow",
+    "WF_Trigger": "Триггер",
+    "WF_Trigger_event_type": "Тип события",
+    "WF_Trigger_type": "Тип триггера",
     "add_icon_event_icon": "fa-square-plus",
     "add_icon_event_tooltip": "Добавить новую иконку",
     "add_option_event_icon": "fa-square-plus",
@@ -742,4 +742,4 @@
     "settings_update_item_warning": "Обновить значение ниже. Будьте осторожны, следуя предыдущему формату. <b>Проверка не выполняется.</b>",
     "test_event_icon": "fa-vial-circle-check",
     "test_event_tooltip": "Сначала сохраните изменения, прежде чем проверять настройки."
-}
+}

front/plugins/omada_sdn_imp/README.md

@@ -41,8 +41,8 @@ The OMADA SDN plugin aims at synchronizing data between NetAlertX and a TPLINK O
 OMADA SDN limitation fixed by the plugin:
 0. OMADA SDN can't use DNS for names and keep using MAC ref: https://community.tp-link.com/en/business/forum/topic/503782
 - when you use an OMADA user Role =  Administrator, the plugin will attempt to fix OMADA's shortcoming and populat the NAME field from NetAlertX (from DNS/DHCP/...)
-![OMADA SDN account page](Oamadaomada_sdn_imp.png)
-- 
+![OMADA SDN account page](omada_account_sample.png)
+
 
 can not fix some of tplinks OMADA SDN own limitations/bugs:
 1. OMADA SDN switches uplinks/downlinks is broken if the default router is not an OMADA native device 

front/plugins/omada_sdn_imp/omada_sdn.py

@@ -285,16 +285,18 @@ def main():
     mylog("verbose", [f"[{pluginName}] login to omada result is: {omada_login}"])
 
     clients_list = callomada(["-t", "myomada", "clients"])
+    client_list_count = clients_list.count("\n")
     mylog(
         "verbose",
-        [f'[{pluginName}] clients found:"{clients_list.count("\n")}"\n{clients_list}'],
+        [f'[{pluginName}] clients found:"{client_list_count}"\n{clients_list}'],
     )
 
     switches_and_aps = callomada(["-t", "myomada", "devices"])
+    switches_and_aps_count = switches_and_aps.count("\n")
     mylog(
         "verbose",
         [
-            f'[{pluginName}] omada devices (switches, access points) found:"{switches_and_aps.count("\n")}" \n  {switches_and_aps}'
+            f'[{pluginName}] omada devices (switches, access points) found:"{switches_and_aps_count}" \n  {switches_and_aps}'
         ],
     )
 

front/workflowsCore.php

@@ -66,6 +66,18 @@ let actionTypes = [
   "update_field", "delete_device"
 ];
 
+let emptyWorkflow = {
+      "name": "New Workflow",
+      "trigger": {
+        "object_type": "Devices",
+        "event_type": "insert"
+      },
+      "conditions": [
+      ],
+      "actions": [     
+      ]
+    };
+
 // --------------------------------------
 // Retrieve and process the data
 function getData() {
@@ -1073,17 +1085,7 @@ function updateWorkflowsJson(workflows)
 // Get empty workflow JSON
 function getEmptyWorkflowJson()
 {
-  return {
-      "name": "New Workflow",
-      "trigger": {
-        "object_type": "Devices",
-        "event_type": "create"
-      },
-      "conditions": [
-      ],
-      "actions": [     
-      ]
-    }
+  return emptyWorkflow;
 } 
 
 // ---------------------------------------------------

mkdocs.yml

@@ -35,7 +35,8 @@ nav:
         - Security: SECURITY.md
       - Advanced guides:
         - Remote Networks: REMOTE_NETWORKS.md      
-        - Notifications Guide: NOTIFICATIONS.md        
+        - Notifications Guide: NOTIFICATIONS.md      
+        - Name Resolution: NAME_RESOLUTION.md  
         - Authelia: AUTHELIA.md   
         - Performance: PERFORMANCE.md      
         - Reverse DNS: REVERSE_DNS.md  
@@ -57,10 +58,12 @@ nav:
         - Icons: ICONS.md
         - Network Topology: NETWORK_TREE.md
   - Troubleshooting:
+      - Inspecting Logs: LOGGING.md
       - Debugging Tips: DEBUG_TIPS.md
       - Debugging Invalid JSON: DEBUG_INVALID_JSON.md
       - Debugging Plugins: DEBUG_PLUGINS.md
       - Debugging Web UI Port: WEB_UI_PORT_DEBUG.md
+      - Debugging Workflows: WORKFLOWS_DEBUGGING.md
   - Development:
       - Plugin and app development:
         - Environment Setup: DEV_ENV_SETUP.md

server/database.py

@@ -75,7 +75,6 @@ class DB():
 
         return arr
 
-
     #-------------------------------------------------------------------------------
     def upgradeDB(self):
         """
@@ -929,4 +928,19 @@ def get_all_devices(db):
     return db.read(sql_devices_all)
 
 #-------------------------------------------------------------------------------
+   
+def get_array_from_sql_rows(rows):
+    # Convert result into list of lists
+    arr = []
+    for row in rows:
+        if isinstance(row, sqlite3.Row):
+            arr.append(list(row))  # Convert row to list
+        elif isinstance(row, (tuple, list)):  
+            arr.append(list(row))  # Already iterable, just convert to list
+        else:
+            arr.append([row])  # Handle single values safely
+
+    return arr
+
+#-------------------------------------------------------------------------------
 

server/workflows/conditions.py

@@ -57,9 +57,7 @@ class ConditionGroup:
 
     def __init__(self, group_json):
 
-        mylog('none', ["[WF] json.dumps(group_json)"])
-        mylog('none', [json.dumps(group_json)])
-        mylog('none', [group_json])
+        mylog('verbose', [f"[WF] ConditionGroup json.dumps(group_json): {json.dumps(group_json)}"])
 
         self.logic = group_json.get("logic", "AND").upper()
         self.conditions = []
@@ -78,6 +76,6 @@ class ConditionGroup:
         elif self.logic == "OR":
             return any(results)
         else:
-            m = f"[WF] Unsupported logic: {self.logic}"
-            mylog('none', [m])
+            m = f"[WF] ConditionGroup unsupported logic: {self.logic}"
+            mylog('verbose', [m])
             raise ValueError(m)

server/workflows/manager.py

@@ -50,20 +50,24 @@ class WorkflowManager:
     def process_event(self, event):
         """Process the events. Check if events match a workflow trigger"""
         
-        mylog('verbose', [f"[WF] Processing event with GUID {event["GUID"]}"])
+        evGuid = event["GUID"]
+        
+        mylog('verbose', [f"[WF] Processing event with GUID {evGuid}"])
 
         # Check if the trigger conditions match
         for workflow in self.workflows:
 
             # Ensure workflow is enabled before proceeding
             if workflow.get("enabled", "No").lower() == "yes":
+                wfName = workflow["name"]
+                mylog('debug', [f"[WF] Checking if '{evGuid}' triggers the workflow '{wfName}'"])
                
                 # construct trigger object which also evaluates if the current event triggers it
                 trigger = Trigger(workflow["trigger"], event, self.db)
 
                 if trigger.triggered:
 
-                    mylog('verbose', [f"[WF] Event with GUID '{event["GUID"]}' triggered the workflow '{workflow["name"]}'"])
+                    mylog('verbose', [f"[WF] Event with GUID '{evGuid}' triggered the workflow '{wfName}'"])
 
                     self.execute_workflow(workflow, trigger)
 
@@ -80,6 +84,8 @@ class WorkflowManager:
     def execute_workflow(self, workflow, trigger):
         """Execute the actions in the given workflow if conditions are met."""
 
+        wfName = workflow["name"]
+
         # Ensure conditions exist
         if not isinstance(workflow.get("conditions"), list):
             m = f"[WF] workflow['conditions'] must be a list"
@@ -93,7 +99,7 @@ class WorkflowManager:
 
             if evaluator.evaluate(trigger):  # If any group evaluates to True
                 
-                mylog('none', [f"[WF] Workflow {workflow["name"]} will be executed - conditions were evaluated as TRUE"])
+                mylog('none', [f"[WF] Workflow {wfName} will be executed - conditions were evaluated as TRUE"])
                 mylog('debug', [f"[WF] Workflow condition_group: {condition_group}"])
 
                 self.execute_actions(workflow["actions"], trigger)

server/workflows/triggers.py

@@ -1,4 +1,5 @@
 import sys
+import json
 
 # Register NetAlertX directories
 INSTALL_PATH="/app"
@@ -7,6 +8,7 @@ sys.path.extend([f"{INSTALL_PATH}/server"])
 import conf
 from logger import mylog, Logger
 from helper import get_setting_value, timeNowTZ
+from database import get_array_from_sql_rows
 
 # Make sure log level is initialized correctly
 Logger(get_setting_value('LOG_LEVEL'))
@@ -27,7 +29,8 @@ class Trigger:
         self.event = event  # Store the triggered event context, if provided
         self.triggered = self.object_type == event["ObjectType"] and self.event_type == event["AppEventType"]
 
-        mylog('verbose', [f"[WF] self.triggered '{self.triggered}'"])
+        mylog('debug', [f"""[WF] self.triggered '{self.triggered}' for event '{get_array_from_sql_rows(event)} and trigger {json.dumps(triggerJson)}' """])
+
 
         if self.triggered:
             # object type corresponds with the DB table name