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

Create Custom Inventory rules

How Custom Inventory rules are implemented

You can create custom applications, and Custom Inventory rules for those applications, so that information about the applications is gathered from managed devices.

Go to the Software Detail page:

Log in to the appliance Administrator Console, https://appliance_hostname/admin. Or, if the Show organization menu in admin header option is enabled in the appliance General Settings, select an organization in the drop-down list in the top-right corner of the page next to the login information.

On the left navigation bar, click Inventory, then click Custom Inventory.

Select Choose Action > New.

Provide general information: Name, Version, Publisher.

For proper downstream reporting, enter this information consistently across software inventory.

Provide the following information:

Option	Description
Restrict To Label	(Optional) The label associated with the item.
Notes	Any additional information you want to provide.
Supported Operating Systems	The operating systems on which the application runs. Applications are deployed only to devices with the selected operating systems.
Custom Inventory Rule	(Optional) The custom inventory rules to apply to the application. Custom inventory rules enable you to detect applications and other items on a device and capture details for reporting. For example, the appliance first verifies whether an application is present on a device before deploying that application. In some instances, however, installed programs do not register in Add/Remove Programs or in standard areas of the registry. In such cases, the appliance might not be able to detect the presence of the application without additional information from the administrator. Therefore, the appliance might repeat the installation each time the device connects. Custom Inventory rules can prevent this repetition. The following rule verifies that the version of the Network Associates VirusScan installed on a device is newer than a given version before deploying it: RegistryValueGreaterThan(HKEY_LOCAL_MACHINE\ Software\Network Associates\TVD\ Network Associates\TVD\Shared Components\ VirusScanEngine\4.0.xx,szDatVersion,4.0.44)

Next to Upload and Associate File, click Choose File to locate a file, then click Open or Choose.

To distribute applications using Managed Installations or File Synchronizations, you need to associate the actual application files with the application.

To prevent the file from being copied to Replication Shares, select Don’t Replicate Associated File. This setting is useful for large files that you do not want users to install from Replication Shares, such as software suites.

Optional: Select a Category and Threat Level for the software.

Click Save.

How Custom Inventory rules are implemented

The KACE Agent receives new Custom Inventory rules during the first device inventory after the rules are created. During that first inventory, the Agent runs the new rules and reports the findings to the appliance.

The Agent runs all rules as well as any other processes scheduled for that session. Therefore, after a device is inventoried, it could take several minutes to run all the rules and other processes before the Agent reports the results.

After the Agent reports the results, the device’s detail page shows the results under Software in Installed Programs and Custom Inventory Fields.

NOTE: The applications with Value Return rules that set a Custom Inventory Field also appear as Installed Programs.

If results are not what you expect, verify that the device has been inventoried recently. The inventory time is shown in the Last Inventory field of the device detail page.

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:

functionName(argument,argument,...)

For specific information on functions and their arguments see:

•

Checking for conditions (conditional rules)

•

Getting values from a device (Custom Inventory Field)

•

Matching filenames to regular expressions

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:

•

Separate arguments by commas.

•

Commas are not allowed anywhere else in the string, except as described in Commas and parentheses as values in a rule.

•

Do not include single or double quotation marks.

•

White space is trimmed from the front and back of each argument.

For example, the following syntaxes are the same:

RegistryValueEquals(HKEY_LOCAL_MACHINE\SOFTWARE\Mozilla\Mozilla Firefox, CurrentVersion, 78.0.2)
RegistryValueEquals(HKEY_LOCAL_MACHINE\SOFTWARE\Mozilla\Mozilla Firefox,CurrentVersion,78.0.2)

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.

•

In arguments where commas are needed as part of the parameter value, the comma needs to be escaped as {{comma}}, except for the last argument in the function.

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.

RegistryValueEquals(HKEY_LOCAL_MACHINE\SOFTWARE\TestSoft, test{{comma}}value, HelloWorld)

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.

RegistryValueEquals(HKEY_LOCAL_MACHINE\SOFTWARE\TestSoft,test1,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.

ShellCommandTextReturn(wmic MEMORYCHIP get BankLabel,Capacity,description,manufacturer)

•

An unmatched literal open parenthesis needs to be escaped as {{op}}. When the parser is tokenizing the arguments for the function, it counts the number of open and close parentheses to determine the end of the function and argument. Therefore, an unmatched literal open parenthesis would throw off the count, and cause the argument value to be parsed incorrectly. If a literal open parenthesis is needed as part of the argument value, it should be represented with {{op}}.

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

ShellCommandTextReturn(echo Hello {{op}} World)

•

Unmatched literal close parentheses needs to be escaped as {{cp}}.

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:

ShellCommandTextReturn(echo Hello {{cp}} World)

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:

•

Conditional rule reference

•

Verifying whether a condition exists (Exists rules)

•

Evaluating device settings (Equals rules)

•

Comparing device values (Greater Than and Less Than rules)

•

Testing for multiple conditions

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

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

Conditional rule reference

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

Table 24. Data types supported for comparison functions
Conditional rule	Data types supported for comparison functions Equals, GreaterThan, LessThan
EnvironmentVariable	DATE, NUMBER, TEXT
FileInfo	DATE, NUMBER, TEXT
FilenamesMatchingRegex	NUMBER
FileVersion	TEXT
PlistValue	NUMBER, TEXT
ProductVersion	TEXT
RegistryValue	TEXT

The following table describes how comparisons are made.

Table 25. How comparisons are made

Data type

Considerations

DATE

•

Before evaluation, target values are parsed as a date using the same rules as in the PHP DateTime class and then normalized to use the following format:

MM/DD/YYYY HH:MM:SS

•

The timestamp listed in the appliance database uses the 24-hour clock (0 – 24 hours).

•

The timestamp listed in the appliance database reflects UTC (Coordinated Universal Time) time, so that it is normalized for all devices, regardless of their respective timezones.

•

If the target value contains only a date, a timestamp will be added that is based upon midnight for UTC.

NUMBER

•

Only whole numbers are evaluated.

•

If a target value contains any other characters (letters, punctuation marks and so on), only the numbers up to the first non-number are evaluated.

For example, if the target value is 52a1, only 52 is evaluated.

•

Only numbers up to the 32-bit integer maximum positive value (2,147,483,647) are supported.

TEXT

•

Values are evaluated verbatim, without any potential formatting changes (as can occur with DATE and NUMBER data types).

•

Text strings are evaluated in lexicographical order.

•

Commas can be present in the strings being evaluated — no escaping is required.

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

Table 26. Conditional rule reference
Syntax	Win	RHEL	OS X	Description
DirectoryExists (path)	X	X	X	Checks for a directory at the specified path on the device.
FileExists (path)	X	X	X	Checks for a file at the specified path on the device. Include the name of the file and extension in the path.
FileVersionEquals (path, version)	X			Verifies that the Version > File Version property of the file specified in the path matches the TEXT value you entered.
FileVersionLessThan (path, version)	X			Verifies that the Version > File Version property of the file you specified as the path is lower than the TEXT value you entered.
FileVersionGreaterThan (path, version)	X			Verifies that the Version > File Version property of the file you specified is higher than the TEXT value you entered.
ProductVersionEquals (path, version)	X			Verifies that the Version > Product Version property of the executable or installation file you specified matches the TEXT value you entered.
ProductVersionLessThan (path, version)	X			Verifies that the Version > Product Version property of the executable or installation file you specified is lower than the TEXT value you entered.
ProductVersionGreaterThan (path, version)	X			Verifies that the Version > Product Version property of the executable or installation file you specified is higher than the TEXT value you entered.
FileInfoGreaterThan (fullpath, attribute, type, value)	X	X	X	Verifies that the File Info property of the executable or installation file you specified is higher than the value you entered.
FileInfoLessThan (fullpath, attribute, type, value)	X	X	X	Verifies that the File Info property of the executable or installation file you specified is lower than the value you entered.
FileInfoEquals (fullpath, attribute, type, value)	X	X	X	Verifies that the attribute of the executable or installation file you specified matches the value you entered.
RegistryKeyExists (registryPath)	X			Verifies that a registry key exists.
RegistryValueEquals (registryPath, valueName, value)	X			Verifies that a registry entry exactly matches the value you specify. Value is compared as TEXT.
RegistryValueLessThan (registryPath, valueName, value)	X			Verifies that the registry entry is lower than the value you specify. Value is a TEXT.
RegistryValueGreaterThan (registryPath, valueName, value)	X			Verifies that the registry entry is higher than the value you specify. Value is a TEXT.
EnvironmentalVariableExists (var)	X	X	X	Verifies that an environment variable with the name you specify exists.
EnvironmentalVariableGreaterThan (var, type, value)	X	X	X	Verifies that the environment variable definition is higher than the value you specify. All three types are valid, TEXT, DATE (in the full format mm/dd/yyyy hh:mm:ss), and NUMBER.
EnvironmentalVariableLessThan (var, type, value)	X	X	X	Verifies that the environment variable definition is lower than the value you specify. All three types are valid, TEXT, DATE (in the full format mm/dd/yyyy hh:mm:ss), and NUMBER.
EnvironmentalVariableEquals (var, type, value)	X	X	X	Verifies that the environment variable definition exactly matches the value you specify. All three types are valid, TEXT, DATE (in the full format mm/dd/yyyy hh:mm:ss), and NUMBER.
PlistValueExists (fullpath, entry)			X	Verifies that a named value exists in a PLIST file.
PlistValueGreaterThan (fullpath, entry, type, value)			X	Verifies that the named value is a NUMBER or TEXT higher than the value you specified.
PlistValueLessThan (fullpath, entry, type, value)			X	Verifies that the named value is a NUMBER or TEXT lower than the value you specified.
PlistValueEquals (fullpath, entry, type, value)			X	Verifies that the named value is a NUMBER or TEXT that exactly matches the value you specified.

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:

•

DirectoryExists (path)

•

FileExists (path)

•

RegistryKeyExists (registryPath)

•

EnvironmentalVariableExists (var)

•

PlistValueExists (fullpath, entry)

•

FilenameMatchingRegexExist (fullpath, regex)

Example: Check for a directory (folder)

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

DirectoryExists(C:\WINDOWS\)

Example: Check for a file

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

FileExists(C:\WINDOWS\notepad.exe)

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:

•

FileVersionEquals (path, version)

•

ProductVersionEquals (path, version)

•

FileInfoEquals (fullpath, attribute, type, value)

•

RegistryValueEquals (registryPath, valueName, value)

•

EnvironmentalVariableEquals (var, type, value)

•

PlistValueEquals (fullpath, entry, type, value)

•

FilenameMatchingRegexEqual (fullpath, regex, value)

Example: Testing JAVA_HOME setting

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

EnvironmentVariableEquals(JAVA_HOME, TEXT, 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:

RegistryValueEquals(HKEY_LOCAL_MACHINE\Software\McAfee\AVEngine, AVDatDate, 2014/03/01)

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:

RegistryValueEquals(HKEY_LOCAL_MACHINE\Software\Microsoft\WindowsNT\

CurrentVersion,CSDVersion,Service Pack 2)

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:

•

FileVersionGreaterThan (path, version) and FileVersionLessThan (path, version)

•

ProductVersionGreaterThan (path, version) and ProductVersionLessThan (path, version)

•

FileInfoGreaterThan (fullpath, attribute, type, value) and FileInfoLessThan (fullpath, attribute, type, value)

•

RegistryValueGreaterThan (registryPath, valueName, value) and RegistryValueLessThan (registryPath, valueName, value)

•

EnvironmentalVariableGreaterThan (var, type, value) and EnvironmentalVariableLessThan (var, type, value)

•

PlistValueGreaterThan (fullpath, entry, type, value) and PlistValueLessThan (fullpath, entry, type, value)

•

FilenameMatchingRegexGreaterThan (fullpath, regex, value) and FilenameMatchingRegexLessThan (fullpath, regex, value)

Example: Testing whether the product version is higher

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

ProductVersionGreaterThan(C:\Program Files\Mozilla Firefox\firefox.exe, 78)

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

ProductVersionEquals(C:\Program Files\Mozilla Firefox\firefox.exe, 78)

OR ProductVersionGreaterThan(C:\Program Files\Mozilla Firefox\firefox.exe,

78)

Example: Testing for a product version range

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

ProductVersionGreaterThan(C:\Program Files\Mozilla Firefox\firefox.exe, 77)
AND ProductVersionLessThan(C:\Program Files\Mozilla Firefox\firefox.exe, 79)

Important:

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:

•

AND operator: All the rules must return true in order for the results to return true and report the application as an Installed Program.

•

OR operator: Only one rule must return true for the application to be reported as an Installed Program.

Important:

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:

Function
(arguments...
) AND Function
(arguments
) AND ...

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:

RegistryKeyExists(registryPath
) AND RegistryValueEquals(registryPath, valueName, value)

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:

Function
(arguments
) OR Function
(arguments
) OR ...

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:

RegistryValueEquals(registryPath, valueName, value) OR
RegistryValueEquals(registryPath, valueName, value)

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

Seleccione su producto:

Con el fin de ofrecerle un mejor servicio, complete el campo Motivo del chat:

Soluciones recomendadas para su problema

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

Create Custom Inventory rules

How Custom Inventory rules are implemented

Syntax for Custom Inventory rules

Checking for conditions (conditional rules)