The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
WAE Design supports tools for customizing the GUI, enabling you to tailor it to meet your specific needs.
WAE Design provides basic tools for incorporating add-ons (scripts or executables) into the WAE Design GUI.
table_extract
, table_edit
, and table_replace
(see the WAE Design Plan Table Schema and CLI Reference).Once registered with the WAE Design GUI, add-ons are accessible from the Add-Ons menu. If you do not see an add-on that you expect, select the Add-Ons->Find Add-Ons menu.
Creating an add-on involves these steps.
Step 1 Create an executable to perform the add-on task. This executable processes specific CLI parameters, which the GUI then uses to pass details of plan files, reports, and options specified through the add-on dialog box. See Construct Add-On Executable.
Step 2 Construct the add-on’s configuration file ( addon.txt
), which contains two tables. See Construct addon.txt.
<AddOnConfigs>
—Defines the add-on name and description, as well as how the executable should be invoked. <AddOnOptions>
—Defines the WAE Design GUI dialog box from which the executable is invoked from the GUI. Step 3 Construct the return-config-file
parameter of the executable to specify the WAE Design GUI behavior upon exiting the add-on. See Construct return-config-file.
Step 4 Register the add-on with the WAE Design GUI, which is putting the executable and config.txt
file where they can be discovered by WAE Design. See Register Add-Ons.
The add-on can invoke any executable file, such as a shell script, Perl script, or binary executable. The executable must recognize the parameters listed in Table 7-1 , which are passed to the add-on executable when it is called from the GUI.
All parameters except -plan-file
are used by the WAE Design GUI to pass a temporary file or directory name to the add-on script. The script then optionally adds the contents to create the desired file or report. For example, you can create an add-on that generates reports on the existing plan file, as well as one that returns a new plan for display in the GUI.
Table 7-1 Parameters Passed by the WAE Design GUI to the Add-On Executable
|
|
---|---|
Required: The plan file in.pln format that is currently active in the GUI. |
|
Optional: A file name to which the add-on saves a modified version of the plan file. The WAE Design GUI opens this new plan file after the add-on has completed. |
|
Optional: A file name to which the add-on writes a report in PDF format. When exiting the add-on, this report is opened using the default PDF viewer. For information on creating PDF reports, see the Reporting Tools chapter. |
|
Optional: A directory name in which the add-on creates a report that is imported into the currently active plan file and opens the report to its first section. The ShowReport value in the <AddOnReturnConfig> table can show this same report. The ShowReport value also overrides the report-dir value. See the Construct return-config-file section. For information on creating reports that can be stored in plan files, see the Reporting Tools chapter. |
|
Optional: A file name to which the add-on writes a plain text report section. The WAE Design GUI places this report section in an Add-Ons report in the active plan file. This parameter is available for backward compatibility. We recommend you use the report-dir parameter instead. The ShowReport value in the <AddOnReturnConfig> table overrides this property value. See the Construct return-config-file section. |
|
The file name to which the add-on writes the instructions on WAE Design GUI behavior after the add-on has completed. This file contains an <AddOnReturnConfig> table. For information, see theConstruct return-config-file section. This parameter is required if using the report-file parameter. |
The add-on can generate error messages and warnings by writing them to the standard output to the GUI log window (accessed via the Window->Log Window menu).
The add-on can inform the WAE Design GUI of its progress by writing the percentage completed to the standard output. This must be a single line containing a number followed by the '%'
character. The GUI displays this progress in a progress bar while the add-on is running.
A return value of 0 from the add-on indicates that the add-on ran successfully. Any other value indicates an add-on failure.
The addon.txt
configuration file contains two tables.
<AddOnConfigs>
—Defines the add-on name, provides a description of the add-on, and identifies how to invoke the executable should be invoked ( Table 7-2 ). <AddOnOptions>
—Optional: Defines input fields in the add-on dialog box ( Table 7-3 ). A CLI parameter is specified for each field, and these are passed to the executable, together with the input values. The rows are sequentially read.Table 7-3 <AddOnOptions> Table
The file named by the return-config-file
parameter stores the return configuration information in the <AddOnReturnConfig>
table ( Table 7-4 ). This table contains a pair of columns, Property and Value, where the values define the WAE Design GUI behavior upon exiting the add-on ( Table 7-4 ). For information on the GUI behavior of views, traffic levels, service classes, and queues see the WAE Design User Guide. For information on plot layouts and traffic utilization colors, see the WAE Network Visualization Guide.
Table 7-4 <AddOnReturnConfig> Properties and Values
|
|
---|---|
Output (resulting) plan file name. The string can contain a $1 variable, which is the name of the input plan file (without file extension). The default is $1-out. Example: If the input plan file name is euro_geo.pln, by default the output file name is euro_geo-out.pln. |
|
The GUI displays the specified layout view. If not specified, the GUI displays the Default layout, which is customary for a newly opened plan file. |
|
The GUI displays traffic for the specified queue. If both ServiceClass and Queue are specified, the ServiceClass value has priority. |
|
The GUI displays traffic for the specified service class. If not specified, the GUI displays undifferentiated traffic. |
|
The GUI opens the report, including the report-dir report, which should be inserted into the plan before this rule is applied. |
|
The report opened by ShowReport opens to this section. If not specified, the report opens to the first section. |
|
The GUI displays this traffic level. If not specified, the GUI displays the Default traffic level, which is customary for a newly opened plan file. |
|
The GUI fills interfaces with these colors to show levels of traffic utilization. If not specified, the default threshold settings and colors are used. Following is the format, where threshold is a real number and colors are of the form #RRGGBB (standard HTML color names). Format: threshold%<=color<=threshold% |
|
The GUI displays this user-defined plot view. If both View and UserView are specified, the View value has priority. For information on creating plot views, see the Customized Network Plot Views section. |
|
The GUI displays one of these views. If not specified, the GUI displays whichever view is appropriate for the output plan file. |
To register an add-on with WAE Design, create a subdirectory for the add-on in the $CARIDEN_HOME/addons
directory. At a minimum, this directory must contain the addon.txt
configuration file that defines the dialog box and information about the executable.
WAE Design adds a menu item in the Add-Ons menu using the Name parameter in the <AddOnConfigs> table. If this parameter is omitted, WAE Design uses the name of the subdirectory.
To create multiple levels of sub-menus in the WAE Design GUI, simply create nested subdirectories. See for an example.
Add-ons and their sub-menus appear in the Add-Ons menu the next time you launch the GUI, or after you select the Add-Ons->Find Add-Ons menu.
Figure 7-1 Example Add-On Submenus
WAE Design includes three example add-ons: Circuit Upgrade, Circuit Utilization Report, and Traffic Distribution Report.
The $CARIDEN_HOME/addons/CircuitUpgrade
directory includes a sample add-on named CircuitUpgrade that analyzes the Interfaces table Utilization columns. Upon exiting the add-on dialog box (), the add-on executable does the following.
Figure 7-2 Example Circuit Upgrade Dialog Box
This example <AddOnOptions> table customizes the default sample addon.txt file as follows ().
Figure 7-3 Example Customizable Tabs and Groups
The $CARIDEN_HOME/addons/Reports
directory contains two sub-directories, each containing an add-on, thus demonstrating how to create sub-menus. Each of these add-ons, Circuit Utilization Report and Traffic Distribution Report, demonstrate two key add-on features.
mate_jasper
tool to generate a report based on the current plan file, and opening the resulting PDF report. Each report is based on the.jrxml JasperReports template file input to mate_jasper
. For information on using mate_jasper
, see the Reporting Tools chapter and mate_jasper
Help output.Note To run these example report add-ons, you must have ActivePerl installed if you are running a Windows operating system. (ActivePerl is an open-source Perl scripting language provided by ActiveState.)
WAE Design uses an online detailed geographic map database to draw the detailed map background, which is one of the canvas plot options available in the WAE Design GUI. By default, WAE Design uses a public server whose location is specified in the $CARIDEN_HOME/etc/onlinemapurl.txt
file. You can change this URL to use a different server. If you do change it, we recommend that you comment out the line, and add a new one. This way you can easily revert to the default if needed.
For information on viewing a detailed background map and changing plot options, see the WAE Network Visualization Guide.
By editing the plan file directly (for example, through an add-on), you can add a user-defined static view to display interfaces with customized color fills and fill percentages. The view then appears as an option in the Network Plot drop-down list located in the far left corner of the visualization toolbar.
To create this custom network plot view, create or edit a <PlotViewInterfaces>
table ( Table 7-5 ). You must have an entry (row) for each interface you want you want color filled, and each of these interfaces must have the same PlotView name. For example, shows four interfaces in the user-defined plot view named Affinities.
Table 7-5 <PlotViewInterfaces> Columns
Figure 7-4 Example <PlotViewInterfaces> Table Defining an Affinities View and Coloring Five Interfaces