expanded Plugins readme

back/pialert.py

@@ -4034,8 +4034,6 @@ def process_plugin_events(plugin):
             sql.execute ("INSERT INTO Plugins_Events (Plugin, Object_PrimaryID, Object_SecondaryID, DateTimeCreated, DateTimeChanged, Watched_Value1, Watched_Value2, Watched_Value3, Watched_Value4, Status,  Extra, UserData, ForeignKey) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)", (plugObj.pluginPref, plugObj.primaryId , plugObj.secondaryId , createdTime, plugObj.changed , plugObj.watched1 , plugObj.watched2 , plugObj.watched3 , plugObj.watched4 , plugObj.status , plugObj.extra, plugObj.userData, plugObj.foreignKey ))
 
     # Perform databse table mapping if enabled for the plugin   
-    # "mapped_to_table": "DHCP_Leases", 
-    
     if len(pluginEvents) > 0 and  "mapped_to_table" in plugin:
 
         sqlParams = []        

front/plugins/README.md

@@ -12,7 +12,16 @@ These issues will be hopefully fixed with time, so please don't report them. Ins
 
 ## Overview
 
-PiAlert comes with a plugin system to feed events from third-party scripts into the UI and then send notifications if desired.
+PiAlert comes with a plugin system to feed events from third-party scripts into the UI and then send notifications, if desired. The highlighted functionality this plugin system supports, is dynamic creation of a simple UI to interact with the discovered objects, a mechanism to surface settings of plugins in the UI, or to import objects into existing PiAlert database tables. 
+
+Example use cases for plugins could be:
+
+* Monitor a web service and alert me if it's down
+* Import devices from dhcp.leases files instead/complementary to using PiHole or arp-scans
+* Creating ad-hoc UI tables from existing data in the PiAlert database, e.g. to show all open ports on devices, to list devices that disconnected in the last hour, etc.
+* Using other device discovery methods on the network and importing the data as new devices
+* Creating a script to create FAKE devices based on user input via custom settings
+* ...at this point the limitation is mostly the creativity than the capability (there might be edge cases and need to support more form controls for user input off custom settings, but you probably get the idea)
 
 If you wish to develop a plugin, please check the existing plugin structure. Once the settings are saved by the user they need to be removed from the `pialert.conf` file manually if you want to re-initialize them from the `config.json` of the plugin. 
 
@@ -33,19 +42,7 @@ Again, please read the below carefully if you'd like to contribute with a plugin
 
 More on specifics below.
 
-## Supported data sources
 
-Currently only two data sources are supported:
-
-- Script
-- SQL query on the PiAlert database
-
-You need to set the `data_source` to either `pialert-db-query` or `python-script`:
-
-```json
-"data_source":  "pialert-db-query"
-```
-Any of the above datasources have to return a "table" of the exact structure as outlined below.
 
 ### Column order and values
 
@@ -61,6 +58,23 @@ Any of the above datasources have to return a "table" of the exact structure as
   | 7 | `Extra` | no | Any other data you want to pass and display in PiAlert and the notifications |
   | 8 | `ForeignKey` | no | A foreign key that can be used to link to the parent object (usually a MAC address) |
 
+
+### config.json 
+
+## Supported data sources
+
+Currently only two data sources are supported:
+
+- Script
+- SQL query on the PiAlert database
+
+You need to set the `data_source` to either `pialert-db-query` or `python-script`:
+
+```json
+"data_source":  "pialert-db-query"
+```
+Any of the above datasources have to return a "table" of the exact structure as outlined above.
+
 ### "data_source":  "python-script"
 
  If the datasource is set to `python-script` the `CMD` setting (that you specify in the `settings` array section in the `config.json`) needs to contain a executable linux command, that generates a `last_result.log` file. This file needs to be stored in the same folder as the plugin. 
@@ -144,8 +158,45 @@ Required `CMD` setting example with above query (you can set `"type": "label"` i
         }
 ```
 
+### Mapping the plugin results into a database table
 
-### config.json 
+PiAlert will take the results of the plugin execution and insert these results into a database table, if a plugin contains the property `"mapped_to_table"` in the `config.json` root. The mapping of the columns is defined in the `database_column_definitions` array.
+
+This approach is used to implement the `DHCPLSS` plugin. The script parses all supplied "dhcp.leases" files, get's the results in the generic table format outlined in the "Column order and values" section above and takes individual values and inserts them into the `"DHCP_Leases"` database table in the PiAlert database. All this is achieved by:
+
+1) Specifying the database table into which the results are inserted by defining `"mapped_to_table": "DHCP_Leases"` in the root of the `config.json` file as shown below:
+
+```json
+{
+    "code_name": "dhcp_leases",
+    "unique_prefix": "DHCPLSS",
+    ...
+    "data_source":  "python-script",
+    "localized": ["display_name", "description", "icon"],
+    "mapped_to_table": "DHCP_Leases",    
+    ...
+}
+```
+2) Defining the target column with the `mapped_to_column` property for individual columns in the `database_column_definitions` array of the `config.json` file. For example in the `DHCPLSS` plugin, I needed to map the value of the `Object_PrimaryID` column returned by the plugin, to the `DHCP_MAC` column in the PiAlert database `DHCP_Leases` table. Notice the  `"mapped_to_column": "DHCP_MAC"` key-value pair in the sample below.
+
+```json
+{
+            "column": "Object_PrimaryID",
+            "mapped_to_column": "DHCP_MAC", 
+            "css_classes": "col-sm-2",
+            "show": true,
+            "type": "devicemac",            
+            "default_value":"",
+            "options": [],
+            "localized": ["name"],
+            "name":[{
+                "language_code":"en_us",
+                "string" : "MAC address"
+                }]
+        }
+```
+
+3)  That's it. PiAlert takes care of the rest. It loops thru the objects discovered by the plugin, takes the results line, by line and inserts them into the database table specified in `"mapped_to_table"`. The columns are translated from the generic plugin columns to the target table via the `"mapped_to_column"` property in the column definitions.
 
 #### params
 
@@ -248,7 +299,7 @@ Example:
     
 ##### Supported settings `function` values
 
-You can have any `"function": "my_custom_name"` custom name, however, the ones listed below have a specific functiona attached to them. If you use a custom name, then the setting is mostly used as an input parameter for the `params` section.
+You can have any `"function": "my_custom_name"` custom name, however, the ones listed below have a specific functionality attached to them. If you use a custom name, then the setting is mostly used as an input parameter for the `params` section.
 
 - `RUN` - (required) Specifies when the service is executed
     - Supported Options: "disabled", "once", "schedule" (if included then a `RUN_SCHD` setting needs to be specified), "always_after_scan", "on_new_device"
@@ -301,7 +352,7 @@ Example:
 
 The UI will adjust how columns are displayed in the UI based on the definition of the `database_column_definitions` object. Thease are the supported form controls and related functionality:
 
-- Only columns with `"show": true` and also with at least an english translation will be shown in the UI.
+- Only columns with `"show": true` and also with at least an English translation will be shown in the UI.
 - Supported types: `label`, `text`, `threshold`, `replace`
   - `label` makes a column display only
   - `text` makes a column editable

front/plugins/website_monitor/config.json

@@ -359,7 +359,7 @@
             }],
             "description": [{
                 "language_code":"en_us",
-                "string" : "Services to watch. Enter full URL, e.g. <code>https://google.com</code>."
+                "string" : "Services to watch. Enter full URL, e.g. <code>https://google.com</code>. The values from this setting will be used to replace the <code>{urls}</code> wildcard in the <code>WEBMON_CMD</code> setting."
             }]
         },
         {