KACE Systems Management Appliance 13.0 Common Documents - KACE Service Desk Administrator Guide

Syntax for Custom Inventory rules

Syntax for Custom Inventory rules

Use the correct syntax for function names and arguments in Custom Inventory rules.

Conditional and Value Return rules use the following syntax:

For specific information on functions and their arguments see:

Function syntax

Enter the functionName followed by an opening parenthesis, enclose the arguments with a closing parenthesis. No spaces are allowed between the name of the function and the opening parenthesis.

Argument syntax

Enter argument syntax for all rules except command and regex (regular expression) as follows:

For example, the following syntaxes are the same:

Commas and parentheses as values in a rule

If comma, open parenthesis, or close parenthesis are to be used as values in a rule, they must be escaped as {{comma}}. {{op}}, and {{cp}}, respectively.

For example, if the user want to test against the registry value in which the value name is "test,value", the user would need to escape the comma in this case because registry value name is not the last argument in the Custom Inventory (CI) function.

If the user wants to test against the registry value where the value itself contains a comma, then there is no need to escape, because value is the last argument in the Custom Inventory function. The following Custom Inventory tests registy value HKLM\SOFTWARE\TestSoft\test1 and looks to see if the value is equal to 2,4.

If the Custom Inventory function contains only one parameter, it takes everything between the parentheses as the value for the argument. Commas in this case do not need to be escaped and will be part of the argument to the Custom Inventory function.

For example, if the user wants to echo the string "Hello ( World", then the CI should look like the following:

While the parser is tokenizing the arguments for the function, it counts the number of open and close parentheses in order to determine the end of the function when it encounter the last matched close parentheses. However, if the argument value itself contains a close parenthesis that is not matched, the parenthesis tricks the parser to believe that is the end of the function and the argument value will be truncated prematurely.

If a literal close parentheses is needed as part of the argument value, it must be represented with {{cp}}.

For example, if the user wants to echo the string "Hello ) World", then the CI should look like the following:

Checking for conditions (conditional rules)

Checking for conditions (conditional rules)

You can write Custom Inventory rules that identify whether (true/false) an application is installed.

When using a conditional rule, if the rule returns true, the Display name (Title) of the custom application appears in the Software: Installed Programs section of the Device Detail page in the Inventory section.

The following sections describe the rules that test for conditions:

When the rule returns false, the application does not appear in the Installed Programs section in the device’s inventory details.

TIP: You can view a list of devices that have the item installed on the Inventory > Software > Custom_item: Detail page.

Conditional rule reference

The following table describes which data types can be used for comparison.

The following table describes how comparisons are made.

The following table lists available conditional rules with links to specific details on how to specify the arguments.

For information on Equals, GreaterThan, and LessThan for FilenamesMatchingRegex, see Regular Expression Rule Reference.

Verifying whether a condition exists (Exists rules)

Rules whose name ends with Exists check for the presence of a file, directory, registry key, or other item. If the KACE Agent locates the item on the device, the rule returns true, and the item appears in the device’s Inventory Details as an Installed Program.

Use any of the following Exists rules:

Example: Check for a directory (folder)

The following example tests whether the Windows directory exists on the device:

Example: Check for a file

NOTE: The following example verifies that the pad executable file exists on the device:

Evaluating device settings (Equals rules)

Rules whose name ends with Equals compare the value set on the device to the value you specify in the rule. The rules return true if the values exactly match.

Rules that use arguments with set data types can only compare values of the same type.

Use any of the following Equals rules:

Example: Testing JAVA_HOME setting

To verify that the JAVA_HOME setting is C:\Program Files\Java\jdk1.6.0_02:

Example: Testing McAfee® Registry Entry setting

To check the setting use the same format as the date in the entry:

Example: Detecting Windows 7 Service Pack 1

Windows 7 Service Pack 1 appears in Add/Remove programs for devices that were originally on Windows 7 then upgraded to SP1 only. The default application inventory for this item does not reflect devices that are already on SP1 because they were originally imaged at the SP1 level.

When using the appliance to deploy Windows 7 Service Pack 1, create the following Custom Inventory rule for a custom application:

You can then exclude devices with this item installed to prevent the appliance from trying to deploy the SP2 to devices that are already at that level (that is, Windows 7 devices that have been upgraded, as well as devices originally imaged with SP1).

Comparing device values (Greater Than and Less Than rules)

Functions whose names end with GreaterThan and LessThan compare values as listed in Table 24.

Use any of the following Greater Than and Less Than rules:

Example: Testing whether the product version is higher

To verify that the product version is higher than a given number:

To verify that the production version is a given number or higher, enter the following:

Example: Testing for a product version range

To test whether the product version is within a range, combine less than and greater than rules:

IMPORTANT: Do not enter rules on separate lines. Separate the rules by space only. Having rules on separate lines invalidates the compound rule.

Testing for multiple conditions

You can join rules using AND operators or OR operators to test for multiple conditions.

NOTE: Using both AND and OR operators in the same Custom Inventory rule is not supported. Set up separate applications.

Joining conditional rules produces the following results:

IMPORTANT: Do not enter rules on separate lines. Separate the rules by space only. Having rules on separate lines invalidates the compound rule.

Checking for multiple true conditions (AND)

Use the AND operator to join conditional rules in the Custom Inventory Field when you want the item to be reported as an Installed Program only if all the rules are true.

In the Custom Inventory Field, join rules using the following syntax:

Separate the conditional statements from the operator with spaces.

Example: Checking for a registry key and comparing values

To check for a registry key and a registry entry value on a Windows device use AND to combine the rules as follows:

Checking for one true condition (OR)

When you join rules using the OR operator, if any of the rules in the Custom Inventory Field are true, the application appears in the Installed Program list of the device.

In the Custom Inventory Field, join the rules using the following syntax:

Separate the function statements and operator using a space.

Example: Checking for either registry value

To check that a registry entry is one value or another:

TIP: To specify a range use RegistryValueGreaterThan and RegistryValueLessThan rules joined by the AND operator.

Getting values from a device (Custom Inventory Field)

Getting values from a device (Custom Inventory Field)

The rules that end with ValueReturn enable you to gather information from the device. You can use these rules to collect information that the KACE Agent normally does not collect.

The returned values are set with the custom application display name (Title). This appears on the Device Detail page under Software in Installed Programs and Custom Inventory Fields.

Use the Custom Inventory Field values to manage installations and to distribute software as well as reports, View By filtering, Smart Label search criteria, or any other process that can be performed with an automatically detected setting.

This section covers the following topics:

Value Return rule reference

The following table shows all available value return rules that you can use to set a Custom Inventory Field :

Getting File Information values

You can set the Custom Inventory Field to any of the Windows File Information attributes using the FileInfoReturn rule.

Example: Getting Mozilla Firefox version

The following example sets the Custom Inventory Field for the Mozilla Firefox Product Version as a NUMBER:

In the Custom Inventory Field, enter the following:

Getting registry key values

You can set the Custom Inventory Field to a registry key using the RegistryValueReturn rule. Where the registryPath (on left) is the path to the entry, the valueName (on right) is the key you want to return.

Example: Getting the Mozilla FireFox CurrentVersion key

To set the CurrentVersion registry key as a Custom Inventory Field:

Getting command output

Command rules enable you to set the output of a command to a Custom Inventory Field. The command depends on the command interpreter and executable path on the device.

For example, on Windows devices you can write MS-DOS commands, but not Cygwin-style UNIX commands unless Cygwin is installed and available in the default path for all users.

Use any of the following rules to set the output of the command to a Custom Inventory Field:

Example: Getting uptime on a Mac OS X

To set the uptime as a Custom Inventory Field:

Getting PLIST values

PlistValueReturn rules enable you to set a Property List (PList) key as a Custom Inventory Field.

Example: Getting the system locale

To distribute applications using Managed Installations based on the System-provided language, enter the following rule to get the device locale and then create a corresponding Smart Label that is applied to the device based on the language code reported by the KACE Agent in the Custom Inventory Field:

Getting multiple values

Join ValueReturn rules using either the AND or OR operator. The rule shows the application as an Installed Program, if any of the values are not empty.

The joined values are all set in the same Custom Inventory Field separated by the operator and therefore are technically considered for the purposes of Search Criteria, filters, reports, and other appliance processes as TEXT.

ValueReturn rules joined by the:

In the Custom Inventory field, join rules using the following syntax:

Separate the conditional statements from the operator with spaces. Do not join AND and OR operators in the same rule.

Matching filenames to regular expressions

Matching filenames to regular expressions

Regular expressions match a character or the specified string to the filenames in the specified directory.

This section describes the regular expressions that match filenames in Conditional and Value Return rules using a regular expression.

NOTE: The KACE Agent only provides functions that compare filenames using regular expressions.