External Help

External help provides Traverse operators the ability to write support documentation specific to a department, device or test and tie it directly to that same object via a Help link in the web user interface. This way, less experienced system administrators can be provided with a first line of troubleshooting in the absence of live support. You can also enable actions (e.g., server restart) via the Help links. This is a powerful option, as any number of files can be configured to work in this fashion, enabling a large number of background processes via the Web Application.

The default <TRAVERSE_HOME>/utils/externalTestHelp.pl  perl script scans through the entire <TRAVERSE_HOME>/plugin/help directory tree for help text specific to a department, device or test. This script expects one argument in the following form:

<department_name> | <device_name> | <device_addr> | <test_type> | <test_subtype> | <test_name>

where device_addr can be FQDN or IP address. This has to match what was used for device creation. The field test_name should match the descriptive name that was displayed during test creation (or in test details page).

Note: The perl script converts everything (for example, acct_name and device_name) to lowercase to avoid any case related problems when searching for the file. One or more consecutive space characters in device names and test names are converted to an underscore (_) character. Therefore, the directories and subdirectories must be named in lowercase, spaces substituted with underscore, and special characters formatted the same as the department and device names.

The script searches <TRAVERSE_HOME>/plugin/help according to following algorithm:

1. Search for directory acct_name ELSE use _default_user
2. If found, cd into it.
3. Search for subdirectory device_name ELSE device_addr ELSE _default_device
4.  If found, cd into this sub-directory.
5.  Search for the files in the current directory in the following order:

<test_type>_<test_subtype>_<test_name>.{html,txt} ELSE
<test_type>_<test_subtype>.{html,txt} ELSE
<test_type>.{html,txt} ELSE
default.{html,txt}

1. Display the entire file on stdout (if text, then put HTML tags around the text).
2. If not found, display NO FILE FOUND on stdout in HTML format. The script prints out errors on stdout. The location of the script is specified in web.xml and it can basically be any script or program. It is up to the target script to take the arguments and send back help text in the required format.

For example, to create a help file for device mail_server and a more specific one for the disk_space, in department local_department:

cd <TRAVERSE_HOME>/plugin/help

mkdir -p local_department/mail_server

mkdir -p local_department/_default_device

cd local_department/

vi _default_device/default_html

vi mail_server/snmp_disk.txt

vi mail_server/default.html

It is possible to use your own script, that, for example, connects to a database and retrieves escalation information based on specified criteria.