How to Manage Custom Tools

You are here:

Tools > All tools
Tools > Create tool

Introduction

Custom Tools are tools that help you resolve issues, perform actions, or gather information. They open the door to increased functionality for System Frontier. You can run almost any script on servers, workstations, users, or network devices with the same role-based security found throughout System Frontier.

Managing Custom Tools

When you navigate to the Tools menu, you will see a link to create a tool and a link for all tools. The Custom Tools page is displayed by default:

The main Custom Tools page

Clicking the All tools link also opens the Custom Tools page, where you can run or edit existing Custom Tools. The Create tool link takes you to the Custom Tool (Insert) page where you can create a new Custom Tool. The third link in the Tools menu is called My Jobs and its page displays data and results from previous runs of individual Custom Tools.

A Custom Tool uses a script that you provide. System Frontier runs the script with a multi-threading job engine on the management server.

Supported script languages are:

  • PowerShell
  • Batch
  • VBScript
  • Python
  • SSH Shell
  • other command line script utilities

The Custom Tool Script

You can use existing scripts that your organization has already developed. Review the Custom Tool creation steps in this document to get it ready for use in System Frontier. Of special note is the output format from the script.

The Custom Tool output can be basic text or HTML, which gives you great flexibility in the way your data is presented. The creator of the script may format the output appearance as desired.

Adding a Custom Tool

The Custom Tool (Insert) page

To create a Custom Tool, navigate to Tools > Create tool and fill in these fields:

Name

This is the name of the Custom Tool to be created.

Description

Make sure you are specific and informative in your description.

Category

Choose the appropriate category for your tool, but be sure to not choose the preprocessor category unless the tool being created is going to run as a preprocessor to another tool. The categories are also found in the Lookup Data section of the Settings > Site page and can be modified there, if needed.

Script / Executable

The allowable file types include:

  • .ps1
  • .vbs
  • .wsf
  • .js
  • .bat
  • .cmd
  • .sh
  • .exe
  • Other scripting engines can be loaded via a supported file type.

Click the Create button to generate the tool.

After creating the Custom Tool, you will be redirected to the Custom Tool (Edit) page where you can configure permissions and command-line arguments.

Editing an Existing Custom Tool

The Custom Tool (Edit) page

There are two ways to get to the Custom Tool (Edit) page: automatically, after clicking the Create button on the Custom Tool (Insert) page; or, by clicking on the name of a tool on the Custom Tools page.

To modify a Custom Tool, go to the Custom Tool (Edit) page and fill in the required fields:

Name, Description, Cateogry, and Script / Executable

Look in the Adding a Custom Tool section above for information about these four fields.

Arguments

Arguments are the input variables needed by your script. You can create custom fields to use as inputs or use the built-in variables:

  • {$targethostname}
  • {$targetdomain}
  • {$targetdescription}
  • {$targetstatus}
  • {$targetenvironment}
  • {$targetmanufacturer}
  • {$targetmodel}
  • {$targetcpucount}
  • {$targetcpucores}
  • {$targetcpuspeed}
  • {$targetmemory}
  • {$targetipv4address}
  • {$targetoperatingsystem}
  • {$CurrentUsername}

In the arguments field if you enter this information:

then System Frontier will pass as the -ComputerName variable the target computer name to the script. To clarify how this works, let’s see how a regular script is used and how to make it work as a Custom Tool.

A normal PowerShell script might be run from a command line like this:

The actual script might look like this:

To turn it into a Custom Tool, you’ll just upload that script (Get-OperatingSystem.ps1) as your Script / Executable when you create the Custom Tool. You’d have this as your argument in the Arguments field:

The $targethostname variable will take its input manually when you run the tool from the Tools menu, or automatically when run it from a Container or Computer.

If you run the tool on a Container, the target will be all of the computers in the Container. The tool will run once for each computer in the Container.

Running a Custom Tool on a Container

If you run the tool on a single computer, the target will be that computer.

Running a Custom Tool on a computer

Likewise, if you want to use another built-in input variable, such as Model,

then the computer’s model (as stored in the System Frontier database) will also be passed to the script. Custom fields can also be passed.

Only in SSH commands can input variables be used directly in the script, like this for a shell script named lifecycle.sh:
In order to take advantage of System Frontier’s multi-threading job engine, you must always ensure that {$targethostname} is in the arguments field.

Using Quotes in Arguments

If a variable’s real output might contain a value that would normally need to be surrounded by quotes, this can be accomplished like so: ‘{$targetoperatingsystem}’ (with single quotes for PowerShell and double quotes for most other languages).

Do not use quotes around ListToCsv custom fields for PowerShell.

User Input Fields

If your script requires additional input that is not already built-in, you will need to use a Custom Field.

After your Custom Field is created, you can use it in any Custom Tool.

If your tool does need a custom input variable, go to the Custom Tool (Edit) page and click on the Modify button.

User Input Fields Modify button

The Custom Tool Input page will appear:

The Custom Tool Input page

Select the Custom Field that you have already created and click the Add button. You will then see the newly Mapped Input Field at the bottom:

Currently Mapped Input Fields

Click the Done button and you are taken back to the Custom Tool (Edit) page. In the User Input Fields section and under Variable, you’ll see the Mapped Input Field.

To use this input variable in your script, make it available in your Arguments field:

Adding the Mapped Input Field to the Arguments
Clicking on the Variable in the User Input Fields copies it to the clipboard. Simply paste it into the Arguments field to make things easier.

Through the magic of System Frontier, when you add a Custom Field (Mapped Input Field) to the Custom Tool a pre-built HTML form will be generated at run-time allowing the user to provide input into the new input variable.

Example of automatically generated HTML form allowing input of a Mapped Input Field (Custom Field), in this case PortNumber.

Preprocessor

A preprocessor script, in the form of a separate Custom Tool, can be loaded and executed prior to running a Custom Tool. Use a preprocessor to dynamically populate input field values. If your Custom Tool has a ListBox field for services on a computer, for example, a preprocessor can be used to fill in the dropdown box options with a list of the services automatically so that you can select from them.

Don’t Allow Manual Hostname Input

Checking this option will require users to run the Custom Tool from the Tools tab of the computer. Users will not be able to enter a hostname for the input manually. This can be very helpful if you are running a preprocessor which populates an input field with data from a computer. For instance, if your preprocessor populates a ListBox with services running on a computer, it would be prudent to only allow the Custom Tool to run from the Tools tab of a computer because services may be different per computer and this avoids confusion.

ROI Reporting

Clicking on this link will take you to the ROI Report Settings page where you can configure the Return On Investment for the tool.

Permissions

Select the Roles that require access to this Custom Tool. You can choose more than one. A tool can only be accessed if the user has permission via their role.

Disabled

Select this check box to disable the Custom Tool.

Credential Mapping

If your tool requires a specific Credential, select it here. System Frontier will use the default Credential based on this hierarchy:

Credential usage defaults

Click the Save button to save your changes to the Custom Tool.

Deleting a Custom Tool

To delete a Custom Tool, click the Delete link at the bottom of the Custom Tool (Edit) page.

The bottom of the Custom Tool (Edit) page, showing the Delete link

Running a Custom Tool

There are multiple ways to run a Custom Tool:

  • in a Container
  • on the Tools tab of a computer
  • from the Tools > All tools page
  • through the REST API
Running a Custom Tool on a Container
Running a Custom Tool on a computer
When you run a Custom Tool in a Container or for a computer section, you are presented with a web interface that pre-populates the target computer name(s).
Pre-populated computer name when running a Custom Tool from a computer or Container

To run a tool from the Custom Tools page, select the Custom Tool, then click Open:

Custom Tools page
Running a Custom Tool from the Tools >All tools Custom Tools page

Output

When you click the Run button for a Custom Tool, the job runs and the results are shown.

The Job Detail page

Custom Tool Logging

Every time a Custom Tool is run, the data is logged. This includes the actual output of the tool. The only exception is that any data entered into a masked input field is not stored.

You can view previous results from Custom Tool runs in Reports > Audit History and also under the History tab of the computer.

Audit History
History tab of a computer
Historical results from a Custom Tool

Be sure to read the User Guide for more information.

Was this article helpful?
Dislike 0