The custom device script file (.txt)

Previous  Top  Next

Device scripts in CatTools

Devices scripts are defined within CatTools using text files (.txt files) and are stored in the \Scripts sub folder within the root CatTools directory.

When an activity is run, CatTools reads the name item value in the [device] section from the device type .ini file to determine which device script .txt file it needs to use. Therefore each .txt file must be given the same file name as the name item in the corresponding .ini file.
(Its also recommended that in order to save confusion, the .ini file and .txt files have the same file name apart from the file extension).

For all the predefined device types in CatTools, the associated device script .txt files have been encrypted. They are encrypted for two reasons. The first is to protect our intellectual property. The other is to prevent unauthorised modification of these files which may cause the scripts to fail at runtime.


The custom device script .txt template

CatTools provides a starting point template file (based on a Cisco Router) to help assist in the creation of a new custom device script.
The template file is called Custom.Device.Template.txt and can be found in the \Templates sub folder within the root CatTools directory.

This template file is included as part of the predefined device scripts in CatTools, but is unencrypted. As for all of the CatTools predefined device scripts, it may (as and when required) be subject to updates and modifications with each new release of the CatTools product.
For this reason, you should never modify the template file itself in order to create a new custom device script.
If you need to create a new custom device script, take a copy the template file and save it to the \Scripts sub folder giving it a new file name.

Creating your custom device script .txt file

If adding a new custom device script to CatTools, the first step will therefore be to take a copy of the template file Custom.Device.Template.txt in the \Templates sub folder and save it to the \Scripts sub folder, giving it a file name the same as the value entered for the name item within the device type .ini file [device] section, and end with a .txt file type suffix.

This will give you a new starting point device script file to work with.

For example:
To create a new custom device script for a Cisco ASA Firewall device, you may have created an .ini file Custom.Cisco.FirewallASA.ini which contains the name item in the [device] section of Custom.Cisco.FirewallASA.
Therefore, the custom script file will need to be named Custom.Cisco.FirewallASA.txt.


Editing the .txt file

The next step is to open the .txt file and make any necessary changes in order to get the script to work with your device.

The .txt file is well commented (documented) to provide instructions and assistance in making your modifications, however there are a few important sections at the top of the script file which require further mention.


General:

You may see the following line at the very top of the script:

Attribute VB_Name = "Dev_CustomDeviceTemplate"

This is the Visual Basic module name for the device script file when viewing within the Visual Basic (or equivalent) development environment.
This line won't appear if editing the file in the VB development environment, but may do in others.
"Dev_CustomDeviceTemplate" is the name given to the custom template file module.
If you have a number of custom device files, you may want to consider changing this name to reflect your device script file name. By doing so, you can then open multiple custom device script files (say within a project) in your VB development environment.

If you are using a text based editor to modify your scripts (such as Notepad.exe), then changing the module name is optional, although to avoid confusion you may prefer to change the name anyway.

Option Explicit

The Option Explicit statement enforces a level of compliance for the scripting code. You must therefore explicitly declare all variables using the Dim statement, or if redimensioning, using ReDim. If you attempt to use an undeclared variable name, an error occurs at compile time.
Note: as device script files use the Visual Basic Scripting language (VB Script), there is no declaration of the variable 'types'.


Const declarations:

Below the Option Explicit statement is where all the script constants are declared.

Private Const SCRIPT_NAME = "Device Template"

The SCRIPT_NAME constant is a reference given to the script file. This reference will appear within the Info Log pane and Infolog.txt file whenever the script is called.

Private Const DEVICE_

The DEVICE_ constants are constants which define device configuration or responses from the device, for example: DEVICE_USERNAMEPROMPT = "Username:" implies that every time we encounter a prompt from the device to enter a username, we are expecting to see a "Username:" prompt.

Private Const COMMAND_

The COMMAND_ constants are constants which define commands that CatTools sends to the device in order to perform specific tasks or actions when running an activity. For example: COMMAND_ENTERENABLEMODE = "enable" tells CatTools to send the 'enable' command to instruct the device to enter 'enable mode'.


Notes:

--- SCRIPT NOTES ---

The SCRIPT NOTES section provides useful information and lists tasks that are required to be carried out during the initial script creation phase. You can edit this section as and when you feel it is appropriate. An example may be deleting the initial setup tasks block of text from the SCRIPT NOTES section after you have carried out the initial script setup tasks, as it no longer applies.
Any complex routines or script specific behaviour which may be of assistance to any person maintaining the device scripts, should be mentioned in the SCRIPT NOTES section. They should be either fully documented in the SCRIPT NOTES section, or a reference made to the relevant function where they are fully documented.

--- DEVICE NOTES ---

The DEVICE NOTES section is an area where you can enter any device specific behaviour or quirks which may be of assistance to any person maintaining the device scripts. An example may be: "The device you are creating the custom script for only supports SSH2".


Required functions:

There are a number of functions that must exist within your device script in order for CatTools access the device and run activities. These are:

Login Authentication to the device SendPostLoginCommands Commands to be sent after successful login to device EnterEnableMode To enter privileged mode SendPostEnterEnableModeCommands Commands to set the environment after successfully entering enable mode SendSessionTerminationCommands To send necessary commands to exit or logout of the device

The SendPost... functions do not necessarily have to contain any commands, however the function must exist and return TRUE.
Likewise, if your device does not have the concept of an Enable mode, the device script will still require the EnterEnableMode function, however the function only need include a single line of code sending the return value of TRUE.

Unsupported activities:

The device template file contains a number of activities functions which have a call to the internal CatTools client function cl.CatToolsNoSupport.
You should call cl.CatToolsNoSupport so that a message will be written to the Info Log to inform you that the activity is not supported.

Most activities only require the one line of code call to the cl.CatToolsNoSupport function.

Function Activity_UpdatePassword()

Call cl.CatToolsNoSupport

End Function

Some also require a second line which supplies a return value to the CatTools main activity script.

Function Activity_TFTPUpload(iActionType, sTFTPServer, sTFTPFile, sResponseFile, bDoSaveToNVRAM)

Call cl.CatToolsNoSupport

Activity_TFTPUpload = "Not supported"

End Function

If you decide to add support in your custom device script for any of these activities, you need to ensure that you replace the call to the cl.CatToolsNoSupport function with your new lines of code and also update the return value appropriately if it exists.


Saving the script file

Before CatTools can access the script file you have built, you must save it to the \Scripts folder. Normally you do not have to stop and restart CatTools in order for script file code changes to be picked up, however there may be occasions during testing that you find you may have to do this if the changes are not being recognised.


Testing your custom device scripts

Once you have the scripts set up you can test the new device with CatTools by setting up activities using the new device.
See Testing your custom device for more information and tips.


Send us your working scripts

Once you have successfully created support for your custom device in CatTools, if you would like us to consider adding it as a predefined device type to ship with the product, then please send your custom client script .txt file and custom device type .ini file as an attachment using the product support form on our web site.
There are no guarantees as to when or if the device will be added to the predefined device types in CatTools, as there are a number of factors to consider: e.g. the number of requests for the device, complexity of the script, technical resources available, etc; however all scripts that are sent in will be cataloged for future reference.