The custom activity client script file (.txt)

Activity client 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 script_client item value in the [Activity] section from the activity type .ini file to determine which activity client script file it needs to use.

SolarWinds recommends that in order to save confusion, the .ini file and .txt files have the same file name apart from the file prefix of 'Client.' for the .txt script file)

For all the predefined activity types in CatTools, the associated activity client 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 scripts to fail at run time.

The custom activity client script .txt template

CatTools provides a starting point client script template file to help assist in the creation of a new custom activity client script. The template file is called Client.Custom.Activity.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 activity scripts in CatTools, but is unencrypted. As for all of the CatTools predefined activity 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 activity custom client script. If you need to create a new custom activity client script, take a copy the template file and save it to the \Scripts sub folder giving it a new file name.

Creating your custom activity client script .txt file

If adding a new custom activity client script to CatTools, the first step will therefore be to take a copy of the template file Client.Custom.Activity.Template.txt in the \Templates sub folder and save it to the \Scripts sub folder, giving it with a new file name. You need to ensure the file name you use is the value entered for the script_client item within the activity type .ini file [Activity] section.

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

Editing the client script .txt file

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

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.

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

Attribute VB_Name = "Act_Custom_Template"

This is the Visual Basic module name for the custom activity client 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.

Act_Custom_Template is the name given to the custom template file module. If you have a number of custom activity client script files, you may want to consider changing this name to reflect your custom activity client script file names. By doing so, you can then open multiple custom activity client scripts (say within a project) in your VB development environment.

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

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 behavior which may be of assistance to any person maintaining the activity 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.

ACTIVITY NOTES

The ACTIVITY NOTES section is an area where you can enter any activity specific behavior or quirks which may be of assistance to any person maintaining the activity scripts. An example may be: "The activity allows 3 Options:...", and then goes on to list what each option does and its input values.

Required functions

There is only one function that must exist within your custom activity client script in order for CatTools to run the activity:

Function Client()

You may also define your own Functions or Sub routines in the activity client script, however they must be called from within Function Client(). 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 script file

Before CatTools can access the script file you have built, you must save it to the \Scripts sub 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 activity scripts

Once you have all the custom activity scripts set up, you can test the new activity with CatTools by setting up the activity to run with an existing device. The device selected must have had a .custom file created and contain the necessary code relevant to run your activity, otherwise you will see a error be logged to the Info Log of:

"Client script error: Type Mismatch: [activity name] on line: [line number]"

See Testing your custom activity for more information and tips.

Send us your working scripts

Once you have successfully created support for your custom activity in CatTools, if you would like us to consider adding it as a predefined activity type to ship with the product, then please send your custom client and main script .txt files, the custom activity type .ini file and also an example of a device .custom file which references the custom activity. Please send as an attachment using the Technical Support form on our website.

There are no guarantees as to when or if the activity will be added to the predefined activity types in CatTools, as there are a number of factors to consider: e.g. the number of requests for the activity, complexity of the script, technical resources available, etc; however all scripts that are sent in is cataloged for future reference.