1. Introduction¶
The HEC-DSS Monitoring Module includes a set of jython scripts that can be used to rapidly set up “tools” to execute various automated tasks in HEC-DSSVue.
1.1. Workflow¶
The following workflow is assumed:
- A yaml configuration file defines the tool’s input parameters. The configuration file is saved alongside the HEC-DSS .dss file.
- The
toolbox.Tool
is sub-classed to define the tool. The methodtoolbox.Tool.main()
includes the task logic (e.g. importing data, creating plots, etc.).- The tool is run using the
toolbox.Tool.run()
method.
1.2. Example toolbox¶
Example of a HEC-DSS script using the toolbox.Tool
:
# name=Example tool
# displayinmenu=true
# displaytouser=true
# displayinselector=true
import toolbox as tb
import voluptuous as v
from some_module import do_something
class ExampleTool(tb.Tool):
refreshCatalogue = 1 # Update catalogue when completed
schema = v.Schema({
'folder': unicode,
'files': [
unicode
],
'site': unicode
}, required=True)
def main(self):
do_something(self.config, self.dssFilePath)
self.message = "Test tool successfully completed."
tool = ExampleTool()
tool.run()
The above code should be saved in a file like this
%APPDATA%/Roaming/HEC/HEC-DSSVue/scripts/example_tool.py
for it to show
up in the HEC-DSSVue menu and toolbar.
The corresponding configuration file, for example input.yml
, could look
like this.
folder: C:\some\folder
files:
- file 1.txt
- file 2.txt
site: Site name
...
The configuration file is first validated using the schema
attribute. This
uses the voluptuous library
for validation.
The user is prompted to select the configuration file when running the tool. Alternatively, the tool can be created like this:
tool = ExampleTool(configFileName, fullPathToDssFile)
This would be suitable for unattended execution of the tool.
1.3. “Fixing” the HEC-DSSVue configuration¶
HEC-DSSVue scripts are saved in the
%APPDATA%/Roaming/HEC/HEC-DSSVue/scripts
folder. Scripts in this folder
can be run directly from HEC-DSSVue window.
All scripts are executed within the HEC-DSSVue application (Java-based) using an embedded Python interpreter, Jython 2.2 (a very old version). Install the Jython upgrade for HEC-DSSVue to upgrade to the most recent stable version of Jython. This will also modify the Python search path to include the scripts folder.
1.4. Debugging in HEC-DSSVue¶
To make debugging scripts in HEC-DSSVue easier, the Java console window can be
shown when starting HEC-DSSVue by setting showConsole true
in the
%programfiles(x86)%/HEC/HEC-DSSVue/HEC-DSSVue.config
file. Java and
Jython errors will be displayed in this window.
Alternatively the console output can be inspected from the HEC-DSSVue menu
.