README

Python-based command line tools for accessing a WebCTRL server via its WSDL interface

Prerequisits
------------

1) Python 2.7
2) In order to use the WSDL API you need to download and install the SUDS python package
    Download suds-0.4.tar.gz here: https://pypi.python.org/pypi/suds
	Install via command line: $ sudo pip install suds-0.4.tar.gz
3) If you don't want to execute the scripts from within an IDE (e.g. Pycharm) you could install 
    pythoninstaller to build the tools: $ sudo pip install pyinstaller

Building the tools
------------------

webctrl$ ./build_project.sh

The executables wc_* can be found in ./bin

Add the bin directory to the PATH environment variable (in your ~/.bashrc) in order to be able to
execute the wc_* commands everywhere:
export PATH="$PATH:/path/to/webctrl/bin"

Running the tools
-----------------

e.g.: webctrl$ ./dist/wc_query/wc_query

Use -h or --help with all tools in order to find out more about how to use them.

Short explanation of each tool
------------------------------

wc_query : Query the paths and devices starting from /trees/geographic

wc_getReport : Retrieve a report for a directory or a specific device

wc_getValue : Retrieve the current value of a device

wc_getTrend : Retrieve data and date for a given time period and device

wc_monitor : Monitor a specific controller; every time the value changes time and value are displayed

wc_checkAlarms : Check the alarms of a specified node for alarms; send an e-mail in case an alarm is not
    acknowledged/solved after a given amount of time

Usage of the tools in another python script
-------------------------------------------

Analogous to the command line usage

./wc_query -u wsdl -n '/trees/geographic' -url 'https://webctrl.rz-berlin.mpg.de'

wc_query can be used as follows in another python script, say, ~/test.py:

import wc_query
myDictonary = {'username':'wsdl', 'password':'seife', 'node':'/trees/geographic', 'url':'https://webctrl.rz-berlin.mpg.de'}
wc_query.main(myDictonary)

To be able to import the wc_* tools append to the PYTHONPATH the webctrl directory. To do that there are two possible ways:
    1) Set the PYTHONPATH environment variable in the shell in which you run your python script that uses the tool(s):
        export PYTHONPATH="$PYTHONPATH:/path/to/webctrl"
    2) Set the python path inside the python script before the import statement:
        sys.path.append('/path/to/webctrl')

Set the PATH variable to be able to execute the compiled wc tools system-wide: PATH=$PATH:/path/to/webctrl/bin

Argument passing
----------------

There are three ways to pass arguments to the tools:

1) webctrl$ python wc_query.py -n '/trees/geographic'      or
   webctrl$ ./bin/wc_query -n '/trees/geographic'

2) via a dictonary, myDictionary = {..., 'node':'/trees/geographic', ...}, when using one of the tools in another python
   script: wc_query.main(myDictonary)

3) via the SETTINGS file, e.g.: WC_NODE='/trees/geographic'

To see which arguments are required and which ones are optional type: webctrl$ python wc_*.py -h
All required arguments (except the password for the WebCTRL login) need to be passed in any one of the three above ways.
The password cannot be given via the SETTINGS file. If the password is not specified via -p you will be prompted to
type it interactively. All optional arguments have default values which will be shown to you when using one of the tools.

More detailed explanation of the wc_checkAlarms tool
----------------------------------------------------

wc_checkAlarms checks for all alarms for a given node. For example, if '/trees/geographic' is chosen as node all alarms
in the FHI network are retrieved. The tool checks in an interval (-i option) for new alarms and the status of old
alarms. "Old alarms" are alarms that are already known to the tool but have not yet been acknowledged or solved. Once
an alarm is discovered in an "unnormal" state it is observed: Does it still exist? Has it changed its status? The
second parameter is the -t option: the time that needs to pass for an alarm until an action is taken, that is, until
an e-mail about this alarm is sent. This "take action interval" needs to be bigger than the check-for-new-alarms
interval. As it is done at the moment there will be two e-mails after an alarm has been discovered and while the alarm
remains unchecked. After these two e-mails there will be one e-mail every hour reminding of this alarm. The first two
e-mails go to a person lowest in the hierarchy. For every e-mail to follow the hierarchy increases until no more
increase is possible because no more hierarchies have been specified in the SETTINGS file. This could be a schema
for the setting of times and e-mails:

WC_ALARMS_ALERT_PERIODS = '8-16; 16-22; 22-8'
WC_ALARMS_ALERT_EMAILS = 'person1@hierarchy1.de, person2@hierarchy1.de, ... # person1@hierarchy2.de, ... #
    person1@hierarchy3.de, person2@hierarchy3.de, ...;'
WC_ALARMS_ALERT_EMAILS = 'person1@hierarchy1.de, person2@hierarchy1.de, ... # person1@hierarchy2.de, ... #
    person1@hierarchy3.de, person2@hierarchy3.de, ...;'
WC_ALARMS_ALERT_EMAILS = 'person1@hierarchy1.de, person2@hierarchy1.de, ... # person1@hierarchy2.de, ... #
    person1@hierarchy3.de, person2@hierarchy3.de, ...'

A day is divided up into three time periods - all seperated by a colon(!). You can divide up the day in as many periods
as you like and the times do not necessarily need to be in chronologial order. WC_ALARMS_ALERT_EMAILS specifies the
e-mail addresses per time period (seperated by a colon) and per hierarchy within one time period (seperated by a '#').
More than one person will get a notification if you provide a comma-seperated list of e-mail addresses. You can
specifiy as many WC_ALARMS_ALERT_EMAILS as you like. Within the programm all WC_ALARMS_ALERT_EMAILS lines will be
concatenated. You could also make it really simpel. With the following setting the same person(s) will receive an
e-mail at any time of the day:

WC_ALARMS_ALERT_PERIODS = '0-24'
WC_ALARMS_ALERT_EMAILS = 'person1@hierarchy1.de, person2@hierarchy1.de, ...'

ATTENTION: You should specify as many WC_ALARMS_ALERT_EMAILS lines as there are time periods in
WC_ALARMS_ALERT_PERIODS as exemplified above.