Contents of Package
The contents of the zip file should include:
This scripts is composed of 2 python files:
ApiClient.py
ImportScript.py
ApiClient can be used to interface with the Edge Node’s API but will do nothing if run directly.
ImportScript must be run in the same folder with ApiClient.
The examples folder includes a csv and json export with matching names, as expected by the script
Usage
This script will apply a node or app level configuration json to all of the devices specified in a csv file. The csv and json must have matching names (eg. example123.json, example123.csv) and be placed in the Imports folder. Then run ImportScript.py using python 3. It will connect to each device in order, import the provided configuration json, and restart all currently running apps. Note that this process may take several minutes per device.
MQTT and eACM will be started at the end of the process if they weren’t previously running.
JSON Formatting
The import script expects json files as generated by the Export process, either of the full device (node level export) or an individual app (app level export). At this time, folder level exports and csv exports are not recognized by the import script.
CSV Formatting
The CSV file’s top row must be the header:
Site Name,Edge Device IP,reachable,eACM username,eACM password,OS username,OS password,MQTT GroupID,MQTT NodeID,Broker IP
Each columns meaning is detailed below
Site Name | The unique name for the site, this will be assigned to the to level Node of the edge device. Each Site Name must be unique within the CSV. |
Edge Device IP | The IP address or url the edge device; this is the IP we will attempt to contact. Unless otherwise specified, it will be assumped an IP or url is of the format, Eg “192.168.0.10” will be read as “http://192.168.0.10:8080”. If a different port is expected, or the node is configured for https, that must be included, eg “https://192.168.0.10:8181”. Each Edge Device IP must be unique within the CSV. |
reachable | If this is a lower case x the script will attempt to connect to and configure the device. Otherwise this row will be ignored. |
eACM username | The web interface username used to connect to the Edge Manager website and API. Default: admin |
eACM password | The web interface password used to connect to the Edge Manager website and API. Default: admin |
OS username | The operating system username, not currently used by the script; it can be left blank. |
OS password | The operating system password, not currently used by the script; it can be left blank |
MQTT GroupID | The Group ID to be used by the Sparkplub B publisher. It will only be changed if the json is a node level export or an export of the MQTT app. Note: it will be applied to all sparkplug B publishers. |
MQTT NodeID | The Node ID to be used by the Sparkplub B publisher. It will only be changed if the json is a node level export or an export of the MQTT app. Note: it will be applied to all sparkplug B publishers. Each MQTT Node ID must be unique within the CSV. |
Broker IP | The IP of the broker used by the top level node. If the json is a node export or MQTT app export then this will also overwrite the Host Address of broker objects. |
Output
Depending on the results of running the script, the files will be moved as follows. The files will end up in one of four subfolders of Imports:
Complete - The script has run succesfully on at least one of the devices in the csv. A report.txt file is also generated in this folder to detail which sites are updated, which are not, and what prevented the update. Note that if it took longer than the specified timeout, a site may report the apps failed to restart despite the updates being applied succesfully.
Error - Either the script did not recognize the formatting of the csv or one of the devices in the csv did not recognize the formatting of the json file. Check log for details.
Process - Files should only be here while the script is running; they will be collected from Import, moved to Process, then sent to Error or Complete. Any files that remain here when the program is done indicate an unexpected exception. Check log for further details and contact support if necessary.
Unrecognized - Files that are not csv or json, as well as csv and json files without matching names, will be moved here.
Logs
Two log files will be created in the Logs subfolder, ApiClient.log and ImportScript.log. They can be checked for further details if an error appears in the Complete report.
Troubleshooting
If you experience a timeout durring the process, there are 3 variables at the top of ImportScript.py that can be adjusted.
#Shared timeout and retry parameters to tune if network is difficult
timeOut=40
importTimeOut=1200
retries=Retry(
total=3,
status_forcelist=[429, 500, 502, 503, 504],
method_whitelist=["HEAD", "GET", "POST"]
)
timeOut is used for the timeout of all communications except the json import
importTimeOut only controlls the timeout for the json import
Retry covers all the rules for retries after a timeout or http error; only the total should be adjusted.