The custom activity type file (.ini)

Activity types are defined within CatTools using text files (.ini files) and are stored in the \Activities sub folder within the root CatTools directory. Each .ini file represents a separate item in the 'Type' drop-down list in the Add/Edit scheduled activity details form setup form.

When CatTools starts, it searches for all the .ini files in the \Activities sub folder and reads their contents. All the activity types found are then available for selection in the activity Type drop down when defining activities.

To add a new custom activity type, you need to create a new .ini file defining the activity and its characteristics.

The .ini file sections overview

The contents of the .ini file are divided up within [sections]. The main sections inside the INI file are as follows:

[info] section

This is required and identifies the .ini file as a CatTools file.

[info]
cookie=CatTools
version=3
author=SolarWinds

[Activity] section

This is required and defines the name used within the CatTools user interface, such asthe Activity type drop-down list field, and within scripting. It also defines the unique key (id) of the activity type in the CatTools database.

[Activity]
name=Custom.Activity.Template
script_main=Main.Custom.Activity.Template.txt
script_client=Client.Custom.Activity.Template.txt
description=Collects information from devices and creates a custom report
report_file=%AppPath%Reports\Master Custom Activity Template.txt
report_overwrite=1
client_threads=0
id=3999

Although the file name of the .ini file may be similar (or the same) to the [Activity] section name item, it is the name item that defines the activity name within the user interface and not the .ini file name.

CatTools reserves IDs from 0 to 3999 for predefined activity types. You can use the number range from 4000 to 4999 for the custom activity types you create, however you must ensure the number is unique.

[item] sections (Activity Options)

Each item section defines the input fields used within the CatTools user interface for the Activity setup screens.

[item_value1]
name=Use alternate command
type=string
checkbox_show=1
checkbox_default=0
value_default=
required=0
info="Alternative command to capture data from device."

Each input field in the CatTools user interface for Activity options has a separate [item_xxx] type section.

The name item sets the text (or label) to be displayed next to the input or selection field.
The type item describes the type of input or selection field adjacent to the name text/label.
The checkbox_show and checkbox_default items describe whether a checkbox should be displayed and its default value of checked or unchecked.
The value_default item sets the default value to be used when adding a new activity to the database.
The required item tells the user interface if the field must contain valid data or not. For example this must be an item from within a predefined list or whether the user can enter their own values.
- 0 = not required
- 1 = required
The info item is the description associated with this field. This text is displayed in the status bar of the user interface when a field has focus.

Limiting the range of values

The above [item_value1] section is an example of a checkbox and standard text box input field within the user interface. If you need to limit a range of numerical values that can be entered into an option field, then use the type or range.

The range option example below, contains a checkbox and an input field that accepts numerical values between 1 and 2000.

[item_value2]
name=Days until entries expire
type=range
checkbox_show=1
checkbox_default=0
value_default=30
range_min=1
range_max=2000
required=1
info="Remove entries older than X days from the Master report"

Check box input fields can only accept values of 0 or 1. Any value other than a 1 is considered a 0.

For example, the check box is defaulted to 1 (checked).

[item_value3]
name=Resolve IP addresses to hostnames
type=checkbox
checkbox_show=1
checkbox_default=1
info="Resolve all IP addresses found to hostnames via reverse DNS lookup"

The length of the data that can be entered into each field is determined by the design of the CatTools database. Any data entered via the CatTools user interface that is too long for the field will be truncated accordingly.

The custom activity type .ini template

CatTools provides a starting point template file to help assist in the creation of a new custom activity type. The template file is called Custom.Activity.Template.ini and can be found in the \Templates sub folder. This template file is included as part of the predefined activity types in CatTools. As for all of the CatTools predefined activity types, it may 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 activity type.

If you need to create a new custom activity type, take a copy the template file and save it to the \Activities sub folder giving it a new file name.

Creating your custom activity type .ini file

If adding a new custom activity type to CatTools, the first step is to take a copy of the template file Custom.Activity.Template.ini in the \Templates sub folder and save it to the \Activities sub folder giving it a new file name.

This gives you a new starting point activity type file to work with. When naming the file, try to use the naming convention:

Custom.Type.Name

Custom: the text "Custom" to distinguish custom activity types from CatTools predefined types. They are grouped together in the activity 'Type' drop-down list field.
Type: the type of activity, such as Report, CLI, Connectivity, or Update.
Name: the name of activity, such as ARPTable, SendCommands, PingTest, and BannerText.

Editing the .ini file

The next step is to open the .ini file and make the required changes to the values within each section. Below is an example of an .ini file with a number of items values highlighted.

The most important item values which must be changed are highlighted in red. These items must be unique otherwise your activity type may not appear in the CatTools activity Type dropdown list field.
Items values that are no required to be changed are highlighted in green.
Additional comments are highlighted in Blue.
Do not include any comments in your .ini file.

SolarWinds recommends that anything else that is not highlighted should be left at its default setting. You can customize some of the items, such as the Name and Info items, to make them more relevant to your activity.

The text value within the Name item is the field Label that is displayed within the form.
The text value within the Info item is the text that is displayed in the Status bar when you select the field in the form.

Once you have made your amendments to the .ini file, save it to the \Activities sub folder. Restart CatTools in order for your new custom activity type to be read into the activity 'Type' drop-down list field.

Sample .ini file