Tools are the mechanism by which Systems Directorate executes a user defined task. These tasks can be run from many different parts of the application and are very flexible and are a powerful feature.
Tool Types
Tool types include the following.
| Type | Description |
|---|---|
| External programs or batch files | Any external program located on the agent can be run. This includes executables, batch files, PowerShell scripts, etc. |
| Batch files | A batch file can be pasted into the tool itself and will be written to a temporary file to execute as needed. This is useful because the script does not have to exist on the computer first. |
| PowerShell code | A PowerShell script can be pasted into the tool itself and will be written to a temporary file to execute as needed. |
| Web queries | An URL and a set of input variables can be defined for the tool to use. It can perform GET, POST, or PUT operations, and the result of the query is provided as output. |
| Plugin | This is a user created .NET DLL that the tool will execute a function in. The developer is free to do anything they want with no limits. |
| Python script | Python script is a special case. It is available and run all the time after any of the above tools are executed or it can be used on its own. It provides the tool a way of analyzing returned data and either adding new outputs, or adjusting existing ones. This flexibility is extremely powerful. |
Tool Inputs
A tool gets inputs from three places. The first is a parameter string that the administrator provides when setting up the call to the tool. For example, when setting up a notification method for a user, the parameter could be the email address or pager number. The second input is from the application and depends on the component executing the tool. The third place is from global variables.
- Actions would provide the event message plus all defined variables
- Notifications would provide just the variables
- Scripting would provide anything the script writer desires
Tool Outputs
A tool has four main outputs.
| Output | Description |
|---|---|
| Return Code | This is a simple numeric result returned from the execution of a command. A value of 0 usually indicates success. Many Directorate components may rely on this value alone. |
| Standard Output | This is any text that the command has produced. For example, the output of a DIR command, or delimited data from a special inventory scanning program. |
| Standard Error | This is any error text the external program may have output. |
| Data | This is a collection of key/value pairs that contains the initial input information, plus any outputs that may have been added. This is generally used by web queries, plugins, and Python script. |
| Result List | This is a table of result data instead of a single row. This is used for data collection and monitoring primarily but could be used by other tools as well. |
Running Tools
Depending on where the tool is run from will determine what types of inputs and outputs the tool provides.
When running external programs, batch or PowerShell scripts, the input data and variables are all placed into the environment table with an “SD_” prefix on them. The external program can then use any of that information to perform its task. For example, an Action from monitoring would include all the fields from the event message. Global variables are also available in the environment with a VAR_ prefix on them.
External tools also take a parameter string which the tool can define. The operator can use the parameter string defined by the parent component, or can build one based on the inputs provided to the tool by using macro strings.
For a web query, the input variables are instead defined inside the tool itself by the operator. These are placed onto the query string. The rest of the input variables could be turned on as well if needed.
For plugins and Python script, they have direct access to all the inputs and can use them as needed. They can also add any new values to the output data. Both plugins and Python have complete access to the entire .NET framework libraries on the computer and can perform any task imaginable.
Python script is special since it can also run other tools during its own processing! For example, one tool can execute another tool and then based on the returned data, decide to call additional tools. This is how a workflow can be created by using tools alone.
Storing tool results
The results from a tool execution on the Directorate server can be configured to be saved in the database itself. This allows an operator to go back later to see what tools have been used and what outputs they produced.
Examples
Here are a couple quick examples on how tools can be used.
Notification
A notification tool can be setup to send an email message to a user. As input, it would take the parameter string and then use a built in scripting function called SendEmail.
Calling a 3rd Party Ticketing System
Assuming the 3rd party ticketing system uses a command line tool to generate a ticket and uses input parameters, it could be called either directly or via a batch file.
This is a simple example that creates a SEV3 ticket for Windows Support and provides the message text.
[code]
call maketicket.bat "Windows Support" "SEV3" "${MSG_TEXT}"
[/code]
In real life, this may be a lot more complex depending on the ticketing software used. It might make more sense to use Python script or a plugin if XML documents need to be created and passed as inputs and outputs. A plugin could event make web service calls and return ticket numbers via the output data.