The custom activity device script file (.custom)

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.

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 unauthorized modification of these files which may cause the script to fail at run time.

Device .custom file extension scripts

With the introduction of custom activity scripting in CatTools, in order to facilitate the adding of custom activities to the predefined device types, CatTools now checks for the existence of an associated device .custom file in the \Scripts folder, after loading the encrypted device .txt script file.

If when running an activity an associated device .custom file is found for a device type, the contents of the .custom file are read and appended to the predefined device type encrypted script contents, creating a temporary extended device type script, which is then used for the activity.

The device .custom file and the device encrypted files are merged in this manner every time an activity is run.

A device .custom file is associated with its encrypted script by file name, so for example, to add a .custom file for a Cisco Router, Cisco.Router.General.txt, you need to create a file called Cisco.Router.General.txt.custom in the \Scripts folder.

Whenever you upgrade or reinstall CatTools on your system, the predefined device type and activity type script files are overwritten. By defining your custom activity function calls for devices in a separate .custom file, it ensures that your custom functions do not get inadvertently lost.

The device .custom template

CatTools provides a starting point template file to help assist in the creation of a new custom activity device .custom file. The template file is called Custom.Device.Template.txt.custom and can be found in the \Templates sub folder.

This template file is included as part of the predefined scripts in CatTools, but is unencrypted. As for all of the CatTools predefined scripts, it may (as and when required) be subject to updates and modifications with each new release of the CatTools product.

For this specific reason, you should never modify the template file itself in order to create a new device .custom script.

If you need to create a new device .custom script, then take a copy the template file and save it to the \Scripts sub folder giving it a new file name.

Creating your device .custom script file

If adding a new .custom script to CatTools, the first step will therefore be to take a copy of the template file Custom.Device.Template.txt.custom in the \Templates sub folder and save it to the \Scripts sub folder, giving it with a new file name. You need to ensure you save the file using the same file name, including .txt extension, as its associated encrypted device script file, and append a suffix '.custom'.

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

Example

You have created a new custom activity called "Custom_Report_PortStatus" and want to use this activity with your Cisco IOS switch devices. Your custom activity Client script file Client.Custom.Report.PortStatus.txt needs to call the function Custom_Report_GetPortStatus() in order to send a command, capture port data and parse the results to send back to the activity Client script.

To add this custom activity to the Cisco IOS switches, device type script file Cisco.Switch.IOS.txt, you need to perform the following steps:

Create a .custom file for the Cisco IOS switch device type. Copy the .custom template file Custom.Device.Template.txt.custom from the \Templates sub folder and save it to the \Scripts sub folder with the file name of Cisco.Switch.IOS.txt.custom in order for it to be merged with the Cisco.Switch.IOS.txt script at run-time.
Open the .custom file and delete the example functions.
Add your custom activity function Custom_Report_GetPortStatus() and code. Initially, you may just want to test the function is being called correctly, so below is a simple example of the code needed to add an 'Info' message in the Info Log from within your function.
```
Function Custom_Report_GetPortStatus()
	cl.Log 3, "Testing custom activity: Custom_Report_PortStatus"
End Function
```
Save the file.

Editing the .custom file

There are only three issues to be aware of with regards to editing the .custom script file. After copying the .custom template file in the \Templates sub folder to the \Scripts sub folder:

Do not delete the first line in the template file: Attribute VB_Name = "Dev_CustomDeviceTemplate_custom"
You can modify the value between the quotes, but it must always be defined as the Attribute VB_Name, otherwise a run-time error is likely to occur.
SolarWinds recommends you do not enter any uncommented program code in the header section and most importantly do not add any above the Attribute VB_Name line, otherwise your code may be stripped out or alternatively you may encounter a run-time error.
The SCRIPT NOTES section within the .custom file header is there for your own reference. Please feel free to add your own comments in here if it is of assistance to yourself or another developer at a later date.
Ensure that all program code added is contained within either a Function or a Sub routine. To avoid run-time errors or the risk of redefining a variable or object which is used in the predefined encrypted device script, try keep variable and object declarations limited to the scope of a Function or Sub routine. It is good practice to comment your Functions and Sub routines, so that you or other developers can get an idea of what the function does at a later date.

Saving the .custom script file

Before CatTools can access the .custom 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 recognized.

Testing your custom device .custom scripts

Once you have the scripts set up you can test the custom activity with CatTools by setting up the activity and selecting the device you have created the .custom file for.

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 Technical Support form on our website.

There are no guarantees as to when or if the device is added to the predefined device types in CatTools, as there are a number of factors to consider, such as the number of requests for the device, complexity of the script, or technical resources available. All scripts that are sent in will be cataloged for future reference.

Search SolarWinds Support