AppliesTo Scripting Overview

Introduction

AppliesTo scripting is a method for selecting a set of LogicMonitor resources based on their properties. As discussed in Resource and Instance Properties, these properties may be assigned automatically via basic system information discovery or PropertySource execution, or they may be assigned manually.

As a proprietary LogicMonitor scripting language, AppliesTo scripting queries the resources that you have added into monitoring and returns those resources for which the expression evaluates to TRUE. AppliesTo scripting serves several purposes across LogicMonitor, including:

• Associating LogicModules with resources. AppliesTo scripting expressions, as entered into the Applies To field of a LogicModule definition, determine which resources a LogicModule (DataSource, PropertySource, EventSource, TopologySource, and so on) applies to. For a detailed explanation on how LogicMonitor associates LogicModules with resources, see How DataSources Get Applied to Resources.
• Dynamically grouping resources. As discussed in Device Groups Overview, AppliesTo scripting expressions are used to dynamically organize resources into groups.
• Applying custom resource dashboard templates to resources. AppliesTo scripting can be used to display custom resource dashboards for subsets of resources, as discussed in Graphs Tab.
• Returning resource counts for inclusion on dashboards. Various dashboard widgets including the Pie Chart widget and Big Number widget can be customized to return resource counts based on the results of an AppliesTo scripting query.
• Creating custom AppliesTo functions. As discussed in User-Defined AppliesTo Functions, AppliesTo scripting can be used to create custom AppliesTo functions for reuse across your platform.

AppliesTo Scripting Syntax

The majority of LogicMonitor’s out-of-the-box LogicModules feature AppliesTo expressions that require no customization. However, if you are updating/creating LogicModules, or if you are building AppliesTo expressions in other areas of the product, it’s important to understand how the scripting language operates.

Note: If you are updating an AppliesTo expression for the purpose of changing which resources a LogicModule is associated with, do so with extreme caution as all historical data collected by a LogicModule is lost upon disassociation. As best practice, always test AppliesTo scripting changes before updating the LogicModule definition, as discussed in the Building and Testing AppliesTo Statements section of this support article.

Operators

The following operators are available for use in AppliesTo expressions.

Operator	Behavior
==	equal to
!=	not equal to
>	greater than
>=	greater than or equal to
<	less than
<=	less than or equal to
=~	regular expression equality (case insensitive)
!~	regular expression inequality (case insenstive)
and	logical AND, equivalent to &&
&&	logical and, equivalent to and
or	logical OR, equivalent to ||
||	logical OR, equivalent to or
!	logical NOT
( )	grouping operator

Absolute Functions

The functions true() and false() match all or no resources, respectively. As the true() function will match every resource in your portal, use sparingly, if at all, and with caution. The false() function can be useful to globally disable a LogicModule without deleting it (though be aware any historical data will be lost when a LogicModule is disassociated from a resource). The false() function can also be used with a LogicModule under development to prevent it from being applied to any resources prematurely. Neither function accepts parameters.

Convenience Functions

LogicMonitor maintains a number of built-in functions to identify common categories of resources. Most of these functions inspect the system.sysinfo property (which is populated via WMI (for Windows devices) or SNMP (for Linux, NetApp, Netscaler, Cisco)) and/or the system.categories property (which is most typically populated by PropertySources, although it can be populated manually). Convenience functions do not accept parameters.

Convenience Function	Behavior
isAWSService()	Returns TRUE if the value of the system.devicetype property is “2”.
isAzureService()	Returns TRUE if the value of the system.devicetype property is “4”.
isCisco()	Returns TRUE if the value of “cisco” is contained in the system.sysinfo or system.categories property.
isCollectorDevice()	Returns TRUE if the value of the system.collector property is “true”.
isDevice()	Returns TRUE if the value of the system.devicetype property is “0” or if the value of “collectorDataSources” is contained in the system.categories property.
isFreebsd()	Returns TRUE if the value of “freebsd” is contained in the system.sysinfo or system.categories property.
isF5()	Returns TRUE if the system.sysoid property begins with “1.3.6.1.4.1.3375.2.1.3.4.4” or if the value of “f5” is contained in the system.categories property.
isGCPService()	Returns TRUE if the value of the system.devicetype property is “7”.
isLinux()	Returns TRUE if the value of “linux” is contained in the system.sysinfo or system.categories property and the value of “Cisco IOS” is not present in the system.sysinfo property.
isMisc()	Returns TRUE if none of the criteria for the isWindows(), isLinux(), isNetwork(), isStorage(), and isVirtualization() convenience functions are met.
isNetApp()	Returns TRUE if the value of “netapp” is contained in the system.sysinfo or system.categories property.
isNetflow()	Returns TRUE if the value of the system.enablenetflow property is “true”.
isNetscaler()	Returns TRUE if the value of “netscaler” is contained in the system.sysinfo or system.categories property.
isNetwork()	Returns TRUE if the system.sysinfo or system.categories property contains a value that represents systems considered to be a network. A large number of values are inclusive; see the “isNetwork” AppliesTo function (Settings | AppliesTo Functions | isNetwork) for the complete expression.
isSolaris()	Returns TRUE if the value of “solaris” is contained in the system.sysinfo or system.categories property.
isStorage()	Returns TRUE if the system.sysinfo or system.categories property contains a value that represents systems considered to be storage. A large number of values are inclusive; see the “isStorage” AppliesTo function (Settings | AppliesTo Functions | isStorage) for the complete expression.
isUnix()	Returns TRUE if the value of “solaris” or “linux” or “freebs” is contained in the system.sysinfo or system.categories property.
isVirtualization()	Returns TRUE if the value of “vmware” or “xen” is contained in the system.virtualization property or if the value of “hyperv” is contained in the system.categories property.
isWindows()	Returns TRUE if the value of “windows” or “hyper-v” is contained in the system.sysinfo or system.categories property.
getCollectorVersion()	Returns the value of the system.collectorversion property.

Functions that Operate on Arrays

While most resource properties, whether system or custom, are string or numeric type, there are several which are array type, notably:

• system.categories
• system.groups
• system.staticgroups
• system.ips

There are specific AppliesTo functions for working with arrays.

Function: contains(<array>,"<string>")

This function returns TRUE if the specified string matches an array element. The match is a complete match on the search string, case insensitive. Regex is not supported.

Examples

contains(system.groups,"network")
Matches groups (dynamic and static) at the root of the Resources tree named “network”, “Network”, “nEtWoRk”, and so on.

Note: The system.groups property cannot be used in AppliesTo scripting expressions that are intended to dynamically organize resources into groups. As discussed in Device Groups Overview, if you wish to create a dynamic group that is dependent on group membership, you must use the system.staticgroups property (for example, contains(system.staticgroups,"network").

contains(system.staticgroups,"Acme Corp/Prod")
Matches child groups of “Acme Corp” named “Prod” or “prod”, but not those named “production”, “Prod_QA”, and so on.

Note: Only static group membership (not dynamic group membership) is queried when the system.staticgroups property is referenced.

contains(system.ips,"192.168.170.1")
Matches resources with an IP address of 192.168.170.1.

Note: The contains() function can only be used to match the full IP address of a resource. For partial IP address or range matching, use the join() function.

Function: join(<array>,"<separator>")

This function flattens an array to a string with array elements separated by the designated separator. Required parameters are the array name (for example, system.groups) and the string separator (for example, “,”). Unlike contains(), partial match and regex are supported. When used alone it returns TRUE for resources which have any value set for the specified array property.

Examples

join(system.ips,",")=~"192.168.100."
Matches resources with an IP address on the subnet 192.168.100.X. The ability to match on the partial IP address of a resource is useful for grouping devices by subnet or IP range.

join(system.groups,",")=~"Prod"
Matches resources in groups with names like “Prod”, “production”, “Prod1”, and so on at any level of the Resources tree.

join(system.staticgroups,",")=~"/.*dev"
Matches resources in any non-dynamic child group whose name contains “dev”, “Dev”, “DEV”, and so on.

!join(system.categories,",") Matches any resource for which system.categories is empty. Equivalent to !system.categories.

Function: hasCategory("<string>")

This function queries the system.categories property for an array element that is a complete, case insensitive match for the specified string. Regex is not supported. Returns TRUE if there is a match.

Example

hasCategory("sonicwallfw")

Functions that Operate on Strings and Numbers

The following functions operate on properties that are string or numeric type.

Function: exists("<property value>")

This function returns TRUE if the specified value is assigned to any of the resource’s properties.

Function: sum(x,y,z)

This function returns the sum of the numbers passed as parameters.

Function: startsWith(<property>,"<value>")

This function returns TRUE if the property value starts with the value specified in the function. Typically the value will be a string and should be enclosed in double quotes. Partial match from the beginning of the string is supported; regex is not. It is possible to pass the value as a number, without double quotes. However, partial match is not supported for numeric values, so the match must be complete for the function to return TRUE.

Examples

startsWith(system.sysinfo,"Microsoft") Matches Windows resources.

startsWith(system.collectorversion,"28") Matches resources monitored by Collector versions 28.xxx.

startsWith(system.collectorversion,"28102") Matches resources monitored by Collector version 28.102. Note that this is equivalent to system.collectorversion==23102.

Function: sysoid

This is an alias to the system.sysoid property that removes the need to escape periods in the OID. Use with the ==, =!, =~ and !~ operators to compare resources’ system OIDs to the specified value. For a partial match, use =~ or !~. When used alone, it returns TRUE for resources which have a value set for system.sysoid.

Examples

sysoid!="1.3.6.1.4.1.8072.3.2.10"
Matches resources with system OIDs that are not “1.3.6.1.4.1.8072.3.2.10”.

sysoid=~"8741.1" Matches resources with system OIDs containing “8741.1”.

sysoid
When no value is specified, returns TRUE for all resources which have a value set for this property.

Function: <property name>

Any property name can be referenced as an AppliesTo function. When used alone, it returns TRUE for any resource which has a value set for the specified property. It can be used with operators for comparison purposes.

Examples

system.collectorversion>=28000
Matches resources monitored by Collectors version 28.000 and higher.

system.collectorid!=system.prefcollectorid
Returns TRUE for resources not being monitored by their preferred Collector.

auto.serial.number=~"^C0E" Returns TRUE for resources with values for the auto.serial.number property which start with “C0E”.

Function: getPropValue("<property name>")

If the device property name contains special characters such as “:”, “/”, “*”, “=”, or spaces, you will need to use the getPropValue("<property name>") function. We recommend not having special characters in your property names, but if it can’t be avoided, this function allows you to use the property in an AppliesTo expression.

For example, if you have a property named “SiteA:unit”, and you want to return resources with this property having values 10 to 19, you might initially try:

SiteA:unit=~"[10-19]"

However, you will receive a syntax error informing you that characters in regular expressions must be escaped. To get past the error you will need to use this expression instead:

getPropValue("SiteA:unit")=~"[10-19]"

Note the property name is enclosed in double quotes.

When getPropValue("<property name>") is used alone it returns TRUE for all resources which have a value set for the specified property.

User-Defined Functions

You can define your own AppliesTo convenience functions globally, and those functions can then be called from any location within LogicMonitor that takes AppliesTo scripting as input. As discussed in User-Defined AppliesTo Functions, user-defined convenience functions are created and managed from the AppliesTo Functions page.

Usage Notes

Regex

• Regex matching is not case sensitive. However, this is not a problem since property names and values are not case sensitive in the backend. You can enter mixed-case names and values, and they will be displayed as mixed case where you set them, but this has no effect on how they are processed by AppliesTo functions.
• Regex tokens used in string values should not be escaped.
  join(system.groups,",")=~"qa|dev"
• For a regex token in a string value to be treated as a literal character it must be escaped with “\\”.
  system.sysoid=~"(.+\\.){5}8072"

Other

All property names are referenced as unquoted strings exactly as they appear on the resource Info tab.The exception is when used as a parameter in the getPropValue("<property name>") function, where the property name must be enclosed in double quotes.

Additional Examples

Multiple AppliesTo expressions can be grouped and linked by Boolean operators to make the AppliesTo statement as specific as is required.

isWindows() && (system.sysinfo =~ “x64” || system.sysinfo =~ “Vista”) Returns Windows resources running a 64-bit operating system or Vista.

hasCategory("snmp") && !isWindows() Returns all resources with “snmp” listed as a value in the system.categories property, excluding Windows resources.

isLinux() && system.collectorversion>=28000 && (location=~"Austin" || join(system.groups,",")=~"dev|qa") Returns Linux resources being monitored by Collector version 28 or higher which are either located in Austin or members of a group with a name containing “dev” or “qa”.

Building and Testing AppliesTo Statements

Wherever AppliesTo scripting is accepted as input across the LogicMonitor platform, you will see an Applies To field. The Applies To field directly carries the AppliesTo statement. Accompanying this field is a wizard for more intuitive statement building and test functionality for verifying that the statement is working as intended.

Note: If you are updating an AppliesTo expression for the purpose of changing which resources a LogicModule is associated with, do so with extreme caution as all historical data collected by a LogicModule for a resource is lost upon dissociation. As best practice, always test AppliesTo scripting changes before updating the LogicModule definition.

Building Statements with the AppliesTo Wizard

While you can manually enter an AppliesTo statement directly into the Applies To field, you may find it more efficient to take advantage of the AppliesTo wizard for help in building statements.

Click the Wizard button to open the wizard. The AppliesTo wizard allows you to quickly generate AppliesTo statements that use any of the following criteria to determine resource association:

• Resource type. Selecting the select resource type option allows you to narrow association to those resources that fall into one of several common resource type categories, which are defined using LogicMonitor’s built-in convenience functions. For example, selecting “Cisco” results in an AppliesTo statement consisting of the isCisco() convenience function. If none of the provided resource types are applicable for your use case, select “Others” to build a statement that queries the system.categories property for a particular value.
• Resource group membership. Selecting the select resource groups option allows you to narrow association to those resources that belong to one or more groups and, optionally, their subgroups.
• Resource name or description. Selecting the select resources option allows you to narrow association to manually selected resources, or resources whose hostname or display name contain a particular string.
• Custom. Use the custom query option to manually edit or build upon a statement created by one of the three previous options.

After building an AppliesTo statement using the wizard, click the Save button to save it to the Applies To field. It is strongly recommended that you test the statement (either using the Test button on the wizard or the one located directly beneath the Applies To field) before performing the final form save, as discussed in the following section.

Testing Statements

After creating or editing an AppliesTo statement, it is strongly recommended that you test the statement before saving the form and putting the new statement into production. You can test an AppliesTo statement by clicking the Test button from the wizard or the Test AppliesTo button located directly under the Applies To field.

As shown next, the test functionality returns a simple count of resources returned by the AppliesTo statement, along with a “Show me” hyperlink that, when clicked, opens a window listing details for the matching resources.

If you are making updates to an existing AppliesTo statement, the Affected Items window also lists any resources that were included by the previous query, but would be excluded if the current query was saved and put into production.

The ability to view soon-to-be excluded resources upon statement testing is especially critical if you are making AppliesTo updates within a LogicModule definition. This is because removing the association between a LogicModule and a resource also permanently removes all historical data previously collected by that LogicModule for that resource. By testing first, you are ensuring that any dissociations (and resulting data loss) are intentional.