mirror/NetAlertX
1
0
Fork 0
mirror of https://github.com/jokob-sk/NetAlertX.git synced 2026-05-30 11:37:05 -04:00
Code Issues Packages Projects Releases Wiki Activity

Docs

Browse Source
This commit is contained in:
jokob-sk
2026-05-27 01:34:37 +00:00
parent d4fe94fb7a
commit dfd7256751
3 changed files with 47 additions and 77 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
docs/PLUGINS_DEV.md
View File

@@ -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"

80
docs/PLUGINS_DEV_DATA_CONTRACT.md
View File

@@ -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)

2
docs/WORKFLOW_EXAMPLES.md
View File

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