From dfd725675158152b9af3b77e5dfe155e5438a501 Mon Sep 17 00:00:00 2001 From: jokob-sk Date: Wed, 27 May 2026 01:34:37 +0000 Subject: [PATCH] Docs --- docs/PLUGINS_DEV.md | 42 ++-------------- docs/PLUGINS_DEV_DATA_CONTRACT.md | 80 ++++++++++++++++--------------- docs/WORKFLOW_EXAMPLES.md | 2 +- 3 files changed, 47 insertions(+), 77 deletions(-) diff --git a/docs/PLUGINS_DEV.md b/docs/PLUGINS_DEV.md index 04780588..57193043 100755 --- a/docs/PLUGINS_DEV.md +++ b/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" \ No newline at end of file diff --git a/docs/PLUGINS_DEV_DATA_CONTRACT.md b/docs/PLUGINS_DEV_DATA_CONTRACT.md index e0a0a469..2ca03bca 100644 --- a/docs/PLUGINS_DEV_DATA_CONTRACT.md +++ b/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..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..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) diff --git a/docs/WORKFLOW_EXAMPLES.md b/docs/WORKFLOW_EXAMPLES.md index 5f5da444..f94647f8 100755 --- a/docs/WORKFLOW_EXAMPLES.md +++ b/docs/WORKFLOW_EXAMPLES.md @@ -45,7 +45,7 @@ Sometimes devices are manually archived (e.g., no longer expected on the network ], "enabled": "Yes" } -```` +``` ### 🔍 Explanation