NetAlertX/docs/PLUGINS_DEV_SETTINGS.md

Plugin Settings System

Learn how to let users configure your plugin via the NetAlertX UI Settings page.

Tip

For the higher-level settings flow and lifecycle, see Settings System Documentation.

Overview

Plugin settings allow users to configure:

• Execution schedule (when the plugin runs)
• Runtime parameters (API keys, URLs, thresholds)
• Behavior options (which features to enable/disable)
• Command overrides (customize the executed script)

All settings are defined in your plugin's config.json file under the "settings" array.

Setting Definition Structure

Each setting is a JSON object with required and optional properties:

{
  "function": "UNIQUE_CODE",
  "type": {
    "dataType": "string",
    "elements": [
      {
        "elementType": "input",
        "elementOptions": [],
        "transformers": []
      }
    ]
  },
  "default_value": "default_value_here",
  "options": [],
  "localized": ["name", "description"],
  "name": [
    {
      "language_code": "en_us",
      "string": "Display Name"
    }
  ],
  "description": [
    {
      "language_code": "en_us",
      "string": "Help text describing the setting"
    }
  ]
}

Required Properties

Property	Type	Description	Example
function	string	Unique identifier for the setting. Used in manifest and when reading values. See Reserved Function Names for special values	"MY_CUSTOM_SETTING"
type	object	Defines the UI component and data type	See Component Types
default_value	varies	Initial value shown in UI	"https://example.com"
localized	array	Which properties have translations	["name", "description"]
name	array	Display name in Settings UI (localized)	See Localized Strings
description	array	Help text in Settings UI (localized)	See Localized Strings

Optional Properties

Property	Type	Description	Example
options	array	Valid values for select/checkbox controls	["option1", "option2"]
events	string	Trigger action button: "test" or "run"	"test" for notifications
maxLength	number	Character limit for input fields	100
readonly	boolean	Make field read-only	true
override_value	object	Template-based value override (WIP)	Work in Progress

Reserved Function Names

These function names have special meaning and control core plugin behavior:

Core Execution Settings

Function	Purpose	Type	Required	Options
RUN	When to execute the plugin	select	YES	"disabled", "once", "schedule", "always_after_scan", "before_name_updates", "on_new_device", "before_config_save"
RUN_SCHD	Cron schedule	input	If RUN="schedule"	Cron format: "0 * * * *" (hourly)
CMD	Command/script to execute	input	YES	Linux command or path to script
RUN_TIMEOUT	Maximum execution time in seconds	input	optional	Numeric: "60", "120", etc.

Data & Filtering Settings

Function	Purpose	Type	Required	Options
WATCH	Which columns to monitor for changes	multi-select	optional	Column names from data contract
REPORT_ON	When to send notifications	select	optional	"new", "watched-changed", "watched-not-changed", "missing-in-last-scan"
DB_PATH	External database path	input	If using SQLite plugin	File path: "/etc/pihole/pihole-FTL.db"

API & Data Settings

Function	Purpose	Type	Required	Options
API_SQL	Generate API JSON file	(reserved)	Not implemented	—

Component Types

Text Input

Simple text field for API keys, URLs, thresholds, etc.

{
  "function": "URL",
  "type": {
    "dataType": "string",
    "elements": [
      {
        "elementType": "input",
        "elementOptions": [],
        "transformers": []
      }
    ]
  },
  "default_value": "https://api.example.com",
  "localized": ["name", "description"],
  "name": [{"language_code": "en_us", "string": "API URL"}],
  "description": [{"language_code": "en_us", "string": "The API endpoint to query"}]
}

Password Input

Secure field with SHA256 hashing transformer.

{
  "function": "API_KEY",
  "type": {
    "dataType": "string",
    "elements": [
      {
        "elementType": "input",
        "elementOptions": [{"type": "password"}],
        "transformers": ["sha256"]
      }
    ]
  },
  "default_value": "",
  "localized": ["name", "description"],
  "name": [{"language_code": "en_us", "string": "API Key"}],
  "description": [{"language_code": "en_us", "string": "Stored securely with SHA256 hashing"}]
}

Dropdown/Select

Choose from predefined options.

{
  "function": "RUN",
  "type": {
    "dataType": "string",
    "elements": [
      {
        "elementType": "select",
        "elementOptions": [],
        "transformers": []
      }
    ]
  },
  "default_value": "disabled",
  "options": ["disabled", "once", "schedule", "always_after_scan"],
  "localized": ["name", "description"],
  "name": [{"language_code": "en_us", "string": "When to run"}],
  "description": [{"language_code": "en_us", "string": "Select execution trigger"}]
}

Multi-Select

Select multiple values (returns array).

{
  "function": "WATCH",
  "type": {
    "dataType": "array",
    "elements": [
      {
        "elementType": "select",
        "elementOptions": [{"isMultiSelect": true}],
        "transformers": []
      }
    ]
  },
  "default_value": [],
  "options": ["Status", "IP_Address", "Response_Time"],
  "localized": ["name", "description"],
  "name": [{"language_code": "en_us", "string": "Watch columns"}],
  "description": [{"language_code": "en_us", "string": "Which columns trigger notifications on change"}]
}

Checkbox

Boolean toggle.

{
  "function": "ENABLED",
  "type": {
    "dataType": "boolean",
    "elements": [
      {
        "elementType": "input",
        "elementOptions": [{"type": "checkbox"}],
        "transformers": []
      }
    ]
  },
  "default_value": false,
  "localized": ["name", "description"],
  "name": [{"language_code": "en_us", "string": "Enable feature"}],
  "description": [{"language_code": "en_us", "string": "Toggle this feature on/off"}]
}

Textarea

Multi-line text input.

{
  "function": "CUSTOM_CONFIG",
  "type": {
    "dataType": "string",
    "elements": [
      {
        "elementType": "textarea",
        "elementOptions": [],
        "transformers": []
      }
    ]
  },
  "default_value": "",
  "localized": ["name", "description"],
  "name": [{"language_code": "en_us", "string": "Custom Configuration"}],
  "description": [{"language_code": "en_us", "string": "Enter configuration (one per line)"}]
}

Read-Only Label

Display information without user input.

{
  "function": "STATUS_DISPLAY",
  "type": {
    "dataType": "string",
    "elements": [
      {
        "elementType": "input",
        "elementOptions": [{"readonly": true}],
        "transformers": []
      }
    ]
  },
  "default_value": "Ready",
  "localized": ["name"],
  "name": [{"language_code": "en_us", "string": "Status"}]
}

Using Settings in Your Script

Method 1: Via get_setting_value() Helper

Recommended approach — clean and simple:

from helper import get_setting_value

# Read the setting by function name with plugin prefix
api_url = get_setting_value('MYPLN_API_URL')
api_key = get_setting_value('MYPLN_API_KEY')
watch_columns = get_setting_value('MYPLN_WATCH')  # Returns list if multi-select

# Use in your script
mylog("none", f"Connecting to {api_url} with key {api_key}")

Method 2: Via Command Parameters

For more complex scenarios where you need to pass settings as command-line arguments:

Define params in your config.json:

{
  "params": [
    {
      "name": "api_url",
      "type": "setting",
      "value": "MYPLN_API_URL"
    },
    {
      "name": "timeout",
      "type": "setting",
      "value": "MYPLN_RUN_TIMEOUT"
    }
  ]
}

Update your CMD setting:

{
  "function": "CMD",
  "default_value": "python3 /app/server/plugins/my_plugin/script.py --url={api_url} --timeout={timeout}"
}

The framework will replace {api_url} and {timeout} with actual values before execution.

Method 3: Via Environment Variables (check with maintainer)

Settings are also available as environment variables:

# Environment variable format: <PREFIX>_<FUNCTION>
MY_PLUGIN_API_URL
MY_PLUGIN_API_KEY
MY_PLUGIN_RUN

In Python:

import os

api_url = os.environ.get('MYPLN_API_URL', 'default_value')

Localized Strings

Settings and UI text support multiple languages. Define translations in the name and description arrays:

{
  "localized": ["name", "description"],
  "name": [
    {
      "language_code": "en_us",
      "string": "API URL"
    },
    {
      "language_code": "es_es",
      "string": "URL de API"
    },
    {
      "language_code": "de_de",
      "string": "API-URL"
    }
  ],
  "description": [
    {
      "language_code": "en_us",
      "string": "Enter the API endpoint URL"
    },
    {
      "language_code": "es_es",
      "string": "Ingrese la URL del endpoint de API"
    },
    {
      "language_code": "de_de",
      "string": "Geben Sie die API-Endpunkt-URL ein"
    }
  ]
}

• en_us - English (required)

Examples

Example 1: Website Monitor Plugin

{
  "settings": [
    {
      "function": "RUN",
      "type": {"dataType": "string", "elements": [{"elementType": "select", "elementOptions": [], "transformers": []}]},
      "default_value": "disabled",
      "options": ["disabled", "once", "schedule"],
      "localized": ["name", "description"],
      "name": [{"language_code": "en_us", "string": "When to run"}],
      "description": [{"language_code": "en_us", "string": "Enable website monitoring"}]
    },
    {
      "function": "RUN_SCHD",
      "type": {"dataType": "string", "elements": [{"elementType": "input", "elementOptions": [], "transformers": []}]},
      "default_value": "*/5 * * * *",
      "localized": ["name", "description"],
      "name": [{"language_code": "en_us", "string": "Schedule"}],
      "description": [{"language_code": "en_us", "string": "Cron format (default: every 5 minutes)"}]
    },
    {
      "function": "CMD",
      "type": {"dataType": "string", "elements": [{"elementType": "input", "elementOptions": [], "transformers": []}]},
      "default_value": "python3 /app/server/plugins/website_monitor/script.py urls={urls}",
      "localized": ["name", "description"],
      "name": [{"language_code": "en_us", "string": "Command"}],
      "description": [{"language_code": "en_us", "string": "Command to execute"}]
    },
    {
      "function": "RUN_TIMEOUT",
      "type": {"dataType": "string", "elements": [{"elementType": "input", "elementOptions": [], "transformers": []}]},
      "default_value": "60",
      "localized": ["name", "description"],
      "name": [{"language_code": "en_us", "string": "Timeout"}],
      "description": [{"language_code": "en_us", "string": "Maximum execution time in seconds"}]
    },
    {
      "function": "URLS",
      "type": {"dataType": "array", "elements": [{"elementType": "input", "elementOptions": [], "transformers": []}]},
      "default_value": ["https://example.com"],
      "maxLength": 200,
      "localized": ["name", "description"],
      "name": [{"language_code": "en_us", "string": "URLs to monitor"}],
      "description": [{"language_code": "en_us", "string": "One URL per line"}]
    },
    {
      "function": "WATCH",
      "type": {"dataType": "array", "elements": [{"elementType": "select", "elementOptions": [{"isMultiSelect": true}], "transformers": []}]},
      "default_value": ["Status_Code"],
      "options": ["Status_Code", "Response_Time", "Certificate_Expiry"],
      "localized": ["name", "description"],
      "name": [{"language_code": "en_us", "string": "Watch columns"}],
      "description": [{"language_code": "en_us", "string": "Which changes trigger notifications"}]
    }
  ]
}

Example 2: PiHole Integration Plugin

{
  "settings": [
    {
      "function": "RUN",
      "type": {"dataType": "string", "elements": [{"elementType": "select", "elementOptions": [], "transformers": []}]},
      "default_value": "disabled",
      "options": ["disabled", "schedule"],
      "localized": ["name", "description"],
      "name": [{"language_code": "en_us", "string": "When to run"}],
      "description": [{"language_code": "en_us", "string": "Enable PiHole integration"}]
    },
    {
      "function": "DB_PATH",
      "type": {"dataType": "string", "elements": [{"elementType": "input", "elementOptions": [], "transformers": []}]},
      "default_value": "/etc/pihole/pihole-FTL.db",
      "localized": ["name", "description"],
      "name": [{"language_code": "en_us", "string": "Database path"}],
      "description": [{"language_code": "en_us", "string": "Path to pihole-FTL.db inside container"}]
    },
    {
      "function": "API_KEY",
      "type": {"dataType": "string", "elements": [{"elementType": "input", "elementOptions": [{"type": "password"}], "transformers": ["sha256"]}]},
      "default_value": "",
      "localized": ["name", "description"],
      "name": [{"language_code": "en_us", "string": "API Key"}],
      "description": [{"language_code": "en_us", "string": "PiHole API key (optional, stored securely)"}]
    }
  ]
}

Validation & Testing

Check Settings Are Recognized

After saving your config.json:

1. Restart the backend: Run task [Dev Container] Start Backend (Python)
2. Open Settings page in UI
3. Navigate to Plugin Settings
4. Look for your plugin's settings

Read Setting Values in Script

Test that values are accessible:

from helper import get_setting_value

# Try to read a setting
value = get_setting_value('MYPLN_API_URL')
mylog('none', f"Setting value: {value}")

# Should print the user-configured value or default

Debug Settings

Check backend logs:

tail -f /tmp/log/app.log | grep -i "setting\|MYPLN"

See Also

• Settings System Documentation - Full settings flow and lifecycle
• Quick Start Guide - Get a working plugin quickly
• Plugin Data Contract - Output data format
• UI Components - Display plugin results