Using search templates

Search Templates are saved searches with automated fields that prompt you to make a choice. For example, a search template that finds free disk space per server would prompt you to specify which server from a pull-down list. You select from the list, and the search runs against that server. The search thus serves as a template that you can reuse against any number of servers.

Searching with templates

When you run a search template, you are prompted to provide or select a parameter.

To run a search template:

Run a search from the Search Template list.
In the Search Inputs box, do one of the following:

Choose a value from the pull-down list.
Type in a value manually.

Click Run Search.

Creating search templates

The part of the search template that generates the pull-down list is called an Input. Inputs restrict the search, such as to a single subnet, or to a specific device. Each search template contains at least one input. You can add any number of inputs to a search, anywhere within the search.

Each input includes the following components within double [[]] square brackets, separated by vertical pipe | bars, in this format: [[ID|Prompt|:Values]]

For example: [[1name|System Name|:win_system_names]]

IDs

Use any string, which identifies the input. Each input requries an ID that controls the order of presentation, and enables you to refer to it from multiple places in the search, or even from other inputs. The ASCII collating sequence uses the ID to determine the order in which it is presented, so it is helpful to start the ID with an integer.

Note: The ID cannot contain a vertical pipe | bar or curly {} brackets.

Prompts

Use a human-readable word or phrase that communicates what to expect in the pull-down list.

Note: The prompt cannot contain a vertical pipe | bar or curly {} brackets.

Values

The values are presented as a list of options to choose from a pull-down list, which limits the search. You can construct the list in the following ways:

Typewritten list — Manually type a comma-separated list of constant values. If you use this format: 'foo (0)', then the value in the parentheses is used in the search.

New PQL query — Use a PQL query that generates two columns: description and value. The description is not required, but it makes the list of values easier to manage. If you have a list of IP addresses that you recognize without assistance, you can forego the description. If there are two values for each row of the search, the first is displayed to the user, and the second is used as the parameter value.

Pre-built PQL query — Use the name of a pre-built PQL query from the Parameter Lookup tab to generate a list of values.

Example 1 contains three inputs:

select freespace#history 
from /network/device/wmi/win32_logicaldisk 
where systemname = 
[[1name|System Name|:win_system_names]]
and name = 
[[2|Drive|select name 
from /network/device/wmi/win32_logicaldisk 
where systemname = 
[[1name]]]]

Example 2 contains an input constructed from a query:

SELECT interface from /network/device 
where interface/inet/ip_address = 
'[[1param|All hosts|select interface/inet/ip_address,
coalesce(dns_name || ' - ' || interface/inet/ip_address,
interface/inet/ip_address) 
from /network/device 
where interface/inet/ip_address is not null
order by 2]]'

Example 3 contains an input constructed from a query that enables you to look up the open ports on any single device by selecting the IP address of that device:

SELECT coalesce(system/dns_name, 
    first(interface/inet/ip_address)) as "Device", 
  join(evidence/tcp_port/param/port, ',') 
    as "Open TCP Ports", 
  join(evidence/udp_port/param/port, ',') 
    as "Open UDP Ports" 
from /network/device 
where interface/inet/ip_address = 
'[[1param|All hosts|select first(interface/inet/ip_address),
  coalesce(system/dns_name || ' - ' || 
    first(interface/inet/ip_address),
  first(interface/inet/ip_address)) 
from /network/device 
where interface/inet/ip_address is not null
order by 2]]'
order by 1

Testing Search Templates

Test an input for a search template to make sure it generates the data that you care about.

To test and validate an input, and see what it presents when used:

On your Developer Tools page, click the Search Template Tester tab.
In the Input field, type or paste an input definition, including surrounding [[body of input]] square brackets.
In the screenshot above, the input calls for a list of IP addresses and the corresponding DNS names of interfaces on all devices the network where the interface is not null.
Click Test Search Input.
In the output field, examine the results in the pull-down list. In the above example, the output field is named All hosts.
You might tweak if necessary, to get the output you want.

Customizing template searches

You can take advantage of the searches that your fellow Paglo users have already developed by modifying saved community searches to suit your own unique circumstances. Here's the PQL query that appears in the Search field at the top of your Paglo Web account, when you run this search:

SELECT history(in_octets,out_octets,from_time => '1 day 
ago', agg_function => 'max',series_function => 'diff') 
FROM /network/device/interface 
WHERE inet/ip_address='[[ip1|IP Address|select ip_address 
from /network/device/interface/inet 
where ../in_octets is not null group by ip_address 
order by ip_address]]'

You can replace the bolded section above with the bolded section below. Then substitute machinename and dnsname with those of a device on your own network. Make sure to leave the single quotes intact:

SELECT history(in_octets, out_octets, from_time => '1 day 
ago',  agg_function => 'max',series_function => 'diff') 
FROM /network/device/interface 
WHERE name='machinename' and ../system/dns_name='dnsname'

Using search templates

Searching with templates

Creating search templates

Testing Search Templates

Customizing template searches

How do I find out more?